TrueNAS MCP服务器
](https://www.python.org/downloads/) ](https://github.com/modelcontextprotocol/python-sdk)  ](https://pypi.org/project/truenas-mcp-server/)
一个生产就绪的模型上下文协议（MCP）服务器 TrueNAS核心和规模 系统。使用Claude或其他MCP兼容客户端通过自然语言控制和管理您的TrueNAS存储和虚拟化。
自动变异检测：服务器会自动检测您是连接到TrueNAS Core还是SCALE，并启用相应的功能。
🚀 特性
通用功能（核心和比例）
- 用户管理 -创建、更新、删除用户和管理权限
- 存储管理 -使用完整的ZFS支持管理池、数据集和卷
- 文件共享 -配置SMB、NFS和iSCSI共享
- 快照管理 -自动创建、删除、回滚快照
- 系统监控 -检查系统运行状况、池状态和资源使用情况
TrueNAS比例尺功能（24.04+）
*连接到SCALE时自动启用*
- 应用 -管理基于Docker Compose的TrueNAS应用程序
- Incus实例 -控制增量虚拟机和容器（规模25.04+）
- 传统虚拟机 -管理bhyve虚拟机
企业功能
- 安全操作类型 -用于请求/响应验证的完整Pydantic模型
- 全面的错误处理 -详细的错误消息和恢复指南
- 生产测井 -具有可配置级别的结构化日志记录
- 连接池 -具有重试逻辑的高效HTTP连接管理
- 速率限制 -限制内置速率以防止API滥用
- 基于环境的配置 -通过环境变量灵活配置
📦 安装
uvx快速入门（推荐）
运行TrueNAS MCP服务器的最简单方法是 uvx:
# Run directly without installation
uvx truenas-mcp-server
# Or install globally with uv
uv tool install truenas-mcp-server传统安装
# With pip
pip install truenas-mcp-server
# Or with pipx for isolated environment
pipx install truenas-mcp-server来自源头
git clone https://github.com/vespo92/TrueNasCoreMCP.git
cd TrueNasCoreMCP
pip install -e .🔧 配置
环境变量
创建 .env 文件或设置环境变量：
# Required
TRUENAS_URL=https://your-truenas-server.local
TRUENAS_API_KEY=your-api-key-here
# Optional
TRUENAS_VERIFY_SSL=true # Verify SSL certificates
TRUENAS_LOG_LEVEL=INFO # Logging level
TRUENAS_ENV=production # Environment (development/staging/production)
TRUENAS_HTTP_TIMEOUT=30 # HTTP timeout in seconds
TRUENAS_ENABLE_DESTRUCTIVE_OPS=false # Enable delete operations
TRUENAS_ENABLE_DEBUG_TOOLS=false # Enable debug tools获取API密钥
- 登录TrueNAS Web用户界面
- 首选 设置→ API密钥
- 点击 添加 并创建一个新的API密钥
- 立即复制密钥（不会再次显示）
Claude桌面配置
添加到您的Claude桌面配置 (claude_desktop_config.json):
{
"mcpServers": {
"truenas": {
"command": "uvx",
"args": ["truenas-mcp-server"],
"env": {
"TRUENAS_URL": "https://your-truenas-server.local",
"TRUENAS_API_KEY": "your-api-key-here",
"TRUENAS_VERIFY_SSL": "false"
}
}
}
}备注：这使用 uvx 自动管理Python环境。确保你有 紫外线 安装：
# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh
# or
brew install uv📚 使用示例
使用Claude桌面版
配置后，您可以使用自然语言与TrueNAS交互：
"List all storage pools and their health status"
"Create a new dataset called 'backups' in the tank pool with compression"
"Set up an SMB share for the documents dataset"
"Create a snapshot of all datasets in the tank pool"
"Show me users who have sudo privileges"
# TrueNAS SCALE virtualization examples
"List all running apps and their status"
"Get the configuration for the sonarr app"
"Show me all Incus VMs and containers"
"Update the crypto-nodes VM to use 8 CPUs"
"Restart the plex app"作为Python库
from truenas_mcp_server import TrueNASMCPServer
# Create server instance
server = TrueNASMCPServer()
# Run the server
server.run()程序化使用
import asyncio
from truenas_mcp_server.client import TrueNASClient
from truenas_mcp_server.config import Settings
async def main():
# Initialize client
settings = Settings(
truenas_url="https://truenas.local",
truenas_api_key="your-api-key"
)
async with TrueNASClient(settings) as client:
# List pools
pools = await client.get("/pool")
print(f"Found {len(pools)} pools")
# Create a dataset
dataset = await client.post("/pool/dataset", {
"name": "tank/mydata",
"compression": "lz4"
})
print(f"Created dataset: {dataset['name']}")
asyncio.run(main())🛠️ 可用工具
用户管理
list_users-列出所有用户及其详细信息get_user-获取特定用户信息create_user-创建新用户帐户update_user-修改用户属性delete_user-删除用户帐户
存储管理
list_pools-显示所有存储池get_pool_status-详细的池运行状况和统计数据list_datasets-列出所有数据集create_dataset-使用选项创建新数据集update_dataset-修改数据集属性delete_dataset-删除数据集
文件共享
list_smb_shares-显示SMB/CIFS共享create_smb_share-创建Windows共享list_nfs_exports-显示NFS导出create_nfs_export-创建NFS导出list_iscsi_targets-显示iSCSI目标create_iscsi_target-创建iSCSI目标
快照管理
list_snapshots-显示快照create_snapshot-创建手动快照delete_snapshot-删除快照rollback_snapshot-恢复到快照clone_snapshot-克隆到新数据集create_snapshot_task-设置自动快照
应用程序管理（TrueNAS SCALE）
list_apps-显示所有TrueNAS应用程序的状态get_app-获取详细的应用程序信息get_app_config-获取完整的应用程序配置start_app-启动应用程序stop_app-停止应用程序restart_app-重新启动应用程序redeploy_app-配置更改后重新部署update_app_config-更新应用程序配置
增量实例管理（TrueNAS SCALE）
list_instances-显示虚拟机和容器get_instance-获取实例详细信息start_instance-启动实例stop_instance-停止实例restart_instance-重新启动实例update_instance-更新CPU/内存/自动启动list_instance_devices-显示连接的设备
传统VM管理
list_legacy_vms-显示bhyve虚拟机get_legacy_vm-获取VM详细信息start_legacy_vm-启动虚拟机stop_legacy_vm-停止虚拟机restart_legacy_vm-重新启动虚拟机update_legacy_vm-更新VM配置get_legacy_vm_status-获取VM状态
调试工具（开发模式）
debug_connection-检查连接设置test_connection-验证API连接get_server_stats-服务器统计信息
📄 寻呼和响应控制
所有列表操作都支持分页，以减少使用LLM客户端时的令牌使用。获取操作支持可选的原始API响应包含以进行调试。
分页参数
全部 list_* 工具支持以下参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
limit | integer | 100 | 返回的最大项目数（最大值：500） |
offset | integer | 0 | 要跳过的项目数 |
响应格式：
{
"success": true,
"items": [...],
"metadata": { ... },
"pagination": {
"total": 250,
"limit": 100,
"offset": 0,
"returned": 100,
"has_more": true
}
}使用示例：
"List the first 10 datasets" → limit=10
"Show users 50-100" → limit=50, offset=50
"Get all SMB shares (up to 500)" → limit=500包括原始API响应
获取应用程序、实例和VM的操作支持 include_raw 参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
include_raw | boolean | false | 包含用于调试的完整API响应 |
何时使用 include_raw=true:
- 调试API响应结构
- 访问格式化响应中未包含的字段
- 排除集成问题
工具支持 include_raw:
get_app-应用程序详细信息get_instance-Incus实例详细信息get_legacy_vm-旧VM详细信息
数据集响应控制
这 list_datasets 和 get_dataset 工具支持一个附加参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
include_children | boolean | true | 包含子数据集（可以显著减少有效载荷） |
用途：
"List only top-level datasets" → include_children=false
"Get tank dataset without children" → include_children=false🏗️ 建筑
truenas_mcp_server/
├── __init__.py # Package initialization
├── server.py # Main MCP server
├── config/ # Configuration management
│ ├── __init__.py
│ └── settings.py # Pydantic settings
├── client/ # HTTP client
│ ├── __init__.py
│ └── http_client.py # Async HTTP with retry
├── models/ # Data models
│ ├── __init__.py
│ ├── base.py # Base models
│ ├── user.py # User models
│ ├── storage.py # Storage models
│ ├── sharing.py # Share models
│ ├── app.py # App models (SCALE)
│ ├── instance.py # Incus instance models (SCALE)
│ └── vm.py # Legacy VM models
├── tools/ # MCP tools
│ ├── __init__.py
│ ├── base.py # Base tool class
│ ├── users.py # User tools
│ ├── storage.py # Storage tools
│ ├── sharing.py # Share tools
│ ├── snapshots.py # Snapshot tools
│ ├── apps.py # App tools (SCALE)
│ ├── instances.py # Incus instance tools (SCALE)
│ └── vms.py # Legacy VM tools
└── exceptions.py # Custom exceptions🧪 发展
设置开发环境
# Clone repository
git clone https://github.com/vespo92/TrueNasCoreMCP.git
cd TrueNasCoreMCP
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install in development mode
pip install -e ".[dev]"运行测试
# Run all tests
pytest
# With coverage
pytest --cov=truenas_mcp_server
# Specific test file
pytest tests/test_client.py代码质量
# Format code
black truenas_mcp_server
# Lint
flake8 truenas_mcp_server
# Type checking
mypy truenas_mcp_server📖 文档
🤝 贡献
欢迎投稿！请看 贡献.md 作为指导方针。
- 分叉存储库
- 创建要素分支(
git checkout -b feature/amazing-feature) - 提交您的更改(
git commit -m 'Add amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求
📝 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
🔒 安全
- 永远不要提交API密钥或凭据
- 对敏感数据使用环境变量
- 在生产中启用SSL验证
- 默认情况下限制破坏性操作
- 通过GitHub issues报告安全问题
📞 支持
- 问题:
- 讨论:
🙏 致谢
- Anthropic 对于MCP规范
- TrueNAS 卓越的存储平台
- MCP Python SDK 贡献者
______________________________________________________________________
由...制作❤️ TrueNAS社区