TrueNAS管理协议服务器

TrueNAS主MCP

用于通过AI助手管理TrueNAS系统的模型上下文协议（MCP）服务器。

特性

此MCP服务器提供对TrueNAS API功能的访问，包括：

• 用户管理：列出、获取、创建、更新、删除用户和组
• 游泳池管理：列出池、获取池状态、清理池
• 数据集管理：列出、创建、获取、删除数据集
• SMB股份：列出、创建、删除SMB共享
• NFS导出：列出、创建、删除NFS导出
• ZFS快照：列出、创建、删除、回滚快照
• iSCSI目标：列出、创建、删除iSCSI目标
• 系统监控：获取警报、事件、磁盘运行状况、系统日志
• 虚拟机管理：列出、启动、停止、重新启动、创建、克隆虚拟机
• 网络管理：列出接口、路由、DNS配置
• 服务管理：列出、启动、停止、重新启动服务
• 磁盘管理：列出磁盘，获取磁盘详细信息，SMART状态
• 证书管理：列出并获取证书
• 复制：列出、创建、运行复制任务
• 云同步：列出、创建、运行云同步任务
• Kubernetes/Docker：获取K8s状态，列出Docker镜像（SCALE）
• 任务管理：列出、获取状态、中止运行任务
• 应用程序/监狱：完整的应用生命周期管理（SCALE/CORE）
• 缓存：为频繁访问的数据内置缓存

安装

先决条件

• 锈1.85或更高版本
• 具有API访问权限的TrueNAS SCALE或TrueNAS CORE
• 用于身份验证的API密钥或用户名/密码

从源代码构建

# Clone the repository
git clone https://github.com/hongkongkiwi/truenas-master-mcp.git
cd truenas-master-mcp

# Build the project
cargo build --release

# The binary will be at target/release/truenas-master-mcp

配置

服务器是通过环境变量配置的：

*要么 TRUENAS_API_KEY 或两者 TRUENAS_USERNAME 和 TRUENAS_PASSWORD 必须提供。

CLI选项

服务器还支持命令行选项：

示例.env文件

# Using API key
TRUENAS_SERVER_URL=https://truenas.local
TRUENAS_API_KEY=your-api-key-here

# OR using username/password
TRUENAS_SERVER_URL=https://truenas.local
TRUENAS_USERNAME=admin
TRUENAS_PASSWORD=your-password

# Optional settings
TRUENAS_VERIFY_SSL=true
TRUENAS_TIMEOUT=30

用法

运行服务器

# Load environment variables from .env file
export $(cat .env | xargs)

# Run the server
cargo run

服务器通过stdio进行通信，这是MCP服务器的标准。

与Claude Desktop一起使用

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "truenas": {
      "command": "/path/to/truenas-master-mcp",
      "env": {
        "TRUENAS_SERVER_URL": "https://truenas.local",
        "TRUENAS_API_KEY": "your-api-key-here"
      }
    }
  }
}

与其他MCP客户端一起使用

服务器实现了标准的模型上下文协议。有关如何连接服务器，请参阅MCP客户端的文档。

示例用法

一旦连接到像Claude Desktop这样的MCP客户端，您就可以管理您的TrueNAS系统：

# List all storage pools
list_pools()

# Get details of a specific dataset
get_dataset(dataset_id_or_path="tank/data/mydata")

# Create a new user
create_user(username="newuser", email="user@example.com", full_name="New User")

# List all VMs and start one
list_vms()
start_vm(vm_id=1)

# Check system alerts
get_alerts()

AI使用示例

本节为AI助手提供了如何有效使用TrueNAS MCP工具的示例。

监控系统健康状况

# Get comprehensive system overview
system_info = get_system_info()
alerts = get_alerts()
pools = list_pools()
disk_health = get_disk_health()

# Check for critical issues
if alerts and len(alerts) > 0:
    critical_alerts = [a for a in alerts if a.get("severity") == "CRITICAL"]
    if critical_alerts:
        # Take action on critical alerts
        for alert in critical_alerts:
            print(f"Alert: {alert['message']}")

管理存储

# Find datasets with low space
datasets = list_datasets()
for ds in datasets:
    if ds.get("available", 0) < ds.get("size", 0) * 0.1:
        print(f"Low space: {ds['name']} ({ds['available']} remaining)")

# Create a new dataset for backups
create_dataset(pool_name="tank", dataset_name="backups")

# Take a snapshot before major changes
create_snapshot(dataset="tank/data", snapshot_name="pre-update-$(date +%Y%m%d)")

管理应用程序（SCALE）

# Check app status and health
apps = list_apps()
for app in apps:
    if app.get("state") != "RUNNING":
        print(f"App not running: {app['name']} - {app.get('error', 'Unknown error')}")

# Scale a deployment
scale_app(app_name="my-app", replica_count=3)

# Upgrade an app with available update
upgrade_app(app_name="my-app", upgrade_version="1.2.3")

管理虚拟机

# Find and stop unused VMs
vms = list_vms()
for vm in vms:
    if vm.get("state") == "RUNNING" and vm.get("uptime", 0) > 86400 * 7:
        # VM has been running for more than 7 days
        print(f"Consider restarting: {vm['name']}")

# Clone a VM before testing
clone_vm(vm_id=1, name="vm-test-clone")

处理警报

# Get and categorize alerts
alerts = get_alerts()
for alert in alerts:
    severity = alert.get("severity", "INFO")
    source = alert.get("source", "unknown")
    message = alert.get("message", "")

    if severity == "CRITICAL":
        # Immediately notify and potentially take action
        print(f"CRITICAL: {message}")
        if "disk" in source.lower():
            # Check disk health
            disk = get_disk(disk_name=extract_disk_name(message))
            print(f"Disk SMART status: {disk.get('smart_status')}")

# Dismiss resolved alerts
dismiss_alert(alert_id="alert-123")

# Clear all old alerts
clear_alerts()

批量操作

# Execute multiple operations in sequence
operations = [
    {"name": "list_pools", "arguments": {}},
    {"name": "list_apps", "arguments": {}},
    {"name": "get_alerts", "arguments": {}},
]
results = batch(operations=operations)

HTTP/SSE模式

对于远程访问或基于web的MCP客户端：

# Run in HTTP/SSE mode on port 8080
TRUENAS_SERVER_URL=https://truenas.local TRUENAS_API_KEY=your-key \
  truenas-master-mcp --transport=sse --port=8080

服务器将在以下位置可用：

• SSE流： http://localhost:8080/sse
• POST消息： http://localhost:8080/messages

可用工具

用户管理

• list_users -列出所有用户
• get_user -按ID获取用户
• get_user_by_username -按用户名获取用户

游泳池管理

• list_pools -列出所有存储池
• get_pool_status -获取特定池的状态
• scrub_pool -在储水池上开始擦洗

数据集管理

• list_datasets -列出所有数据集
• get_dataset -获取特定数据集的详细信息
• create_dataset -创建新数据集
• delete_dataset -删除数据集

SMB股份

• list_smb_shares -列出所有SMB共享
• create_smb_share -创建新的SMB共享
• delete_smb_share -删除SMB共享

NFS导出

• list_nfs_exports -列出所有NFS导出
• create_nfs_export -创建新的NFS导出
• delete_nfs_export -删除NFS导出

快照

• list_snapshots -列出所有ZFS快照
• create_snapshot -创建新快照
• delete_snapshot -删除快照

iSCSI目标

• list_iscsi_targets -列出所有iSCSI目标
• create_iscsi_target -创建新的iSCSI目标
• delete_iscsi_target -删除iSCSI目标

应用程序管理（SCALE）

• list_apps -列出所有应用程序
• get_app -获取特定应用程序的详细信息
• start_app -启动应用程序
• stop_app -停止应用程序
• restart_app -重新启动应用程序
• create_app -从目录创建新应用程序
• update_app -更新应用程序配置
• delete_app -删除应用程序
• rollback_app -将应用程序回滚到以前的版本
• get_app_config -获取应用程序配置
• get_app_upgrade_options -获取可用的升级选项
• upgrade_app -升级应用程序
• scale_app -扩展应用程序副本数量

目录和图表发布

• list_catalog_items -列出可用的目录项
• get_catalog -获取目录详细信息
• get_catalog_trains -获取列车版本目录
• get_catalog_item -获取特定目录项详细信息
• list_chart_releases -列出已部署的图表版本
• get_chart_release -获取图表发布详细信息
• get_chart_release_resources -获取图表发布资源

系统监控

• get_system_info -获取系统信息
• get_alerts -获取系统警报
• get_alert_classes -获取警报类别
• dismiss_alert -取消特定警报
• clear_alerts -清除所有系统警报
• get_system_events -获取最近的系统事件/日志
• get_disk_health -获取磁盘运行状况/SMART状态
• check_for_updates -检查系统更新
• reboot_system -重新启动系统（需要confirm=true）
• shutdown_system -关闭系统（需要确认=真）

群组管理

• list_groups -列出所有组
• get_group -按ID获取组
• get_group_by_name -按名称获取组
• create_group -创建新组
• delete_group -删除组

虚拟机管理

• list_vms -列出所有虚拟机
• get_vm -按ID获取VM详细信息
• create_vm -创建新的虚拟机
• update_vm -更新VM配置
• start_vm -启动虚拟机
• stop_vm -停止虚拟机
• restart_vm -重新启动虚拟机
• powercycle_vm -重启（硬重置）虚拟机
• clone_vm -克隆现有虚拟机
• delete_vm -删除虚拟机

网络管理

• list_interfaces -列出所有网络接口
• list_routes -列出所有网络路由
• get_dns -获取DNS配置

服务管理

• list_services -列出所有服务
• get_service -获取服务详细信息
• start_service -启动服务
• stop_service -停止服务
• restart_service -重新启动服务

磁盘管理

• list_disks -列出所有磁盘
• get_disk -按名称获取磁盘详细信息

证书管理

• list_certificates -列出所有证书
• get_certificate -按ID获取证书详细信息

复制

• list_replication_tasks -列出所有复制任务
• get_replication_task -按ID获取复制任务
• create_replication_task -创建新的复制任务
• delete_replication_task -删除复制任务
• run_replication_task -运行复制任务

云同步

• list_cloudsync_tasks -列出所有云同步任务
• get_cloudsync_task -按ID获取云同步任务
• create_cloudsync_task -创建新的云同步任务
• delete_cloudsync_task -删除云同步任务
• run_cloudsync_task -运行云同步任务

任务管理

• list_tasks -列出所有正在运行和最近执行的任务
• get_task_status -获取特定任务的状态
• abort_task -中止正在运行的任务

Kubernetes（SCALE）

• get_kubernetes_status -获取Kubernetes集群状态
• get_kubernetes_nodes -列出Kubernetes节点
• get_kubernetes_pods -列出Kubernetes Pod
• get_kubernetes_services -列出Kubernetes服务

Docker（SCALE）

• list_docker_images -列出所有Docker镜像
• pull_docker_image -拉取Docker镜像

批量操作

• batch -在一次调用中执行多个操作

其他

• get_enclosure -获取机柜信息
• get_support -获取支持信息

监狱管理（仅CORE）

• list_jails -列出所有监狱
• get_jail -通过ID获取监狱详细信息
• get_jail_by_name -按姓名获取监狱详细信息
• create_jail -新建监狱
• update_jail -更新监狱配置
• delete_jail -删除监狱
• start_jail -开办监狱
• stop_jail -阻止监狱
• restart_jail -重新启动监狱
• clone_jail -克隆监狱
• list_jail_fstabs -列出监狱fstab条目

其他

• get_enclosure -获取机柜信息
• get_support -获取支持信息

发展

运行测试

cargo test

检查代码

cargo fmt
cargo clippy

释放建筑

cargo build --release

码头工人

Docker文件用于容器化部署：

# Build the image
docker build -t truenas-master-mcp .

# Run the container
docker run -d \
  -p 3000:3000 \
  -e TRUENAS_SERVER_URL=https://truenas.local \
  -e TRUENAS_API_KEY=your-api-key \
  --name truenas-mcp \
  truenas-master-mcp

# Build for specific platform
docker buildx build --platform linux/amd64,linux/arm64 -t truenas-master-mcp --push .

API兼容性

此服务器通过REST API v2.0支持TrueNAS SCALE和TrueNAS CORE。集 TRUENAS_VERSION=scale （默认）适用于TrueNAS SCALE或 TRUENAS_VERSION=core TrueNAS CORE。

服务器提供80多种工具，包括：

• 用户和组管理
• 池、数据集、共享、快照和iSCSI管理
• VM、网络和服务管理
• 应用程序管理（仅限SCALE）
• 目录和图表发布权限
• 复制和云同步
• 磁盘和证书管理

许可证

麻省理工学院

贡献

欢迎投稿！请打开问题或提交拉取请求。