金大哥 - TrueNasCoreMCP MCP 详情

article

README

🚀 TrueNAS Core MCP 服务器

TrueNAS Core MCP 服务器是一个基于模型上下文协议（MCP）的服务器，它允许 Claude Desktop（或任何 MCP 客户端）通过 TrueNAS API 与 TrueNAS Core 系统进行交互。

✨ 主要特性

用户管理：列出用户、获取用户详细信息
系统信息：获取 TrueNAS 系统信息
存储管理：列出存储池、数据集，创建数据集
共享管理：列出并创建 SMB 共享
快照管理：创建 ZFS 快照

📦 安装指南

前提条件

Python 3.8 或更高版本
具备 API 访问权限的 TrueNAS Core 系统
Claude Desktop（或任何兼容 MCP 的客户端）
TrueNAS API 密钥

安装步骤

克隆此仓库：

git clone https://github.com/vespo92/TrueNasCoreMCP.git
cd truenas-core-mcp

创建虚拟环境：

python -m venv venv

# 在 Windows 上：
venv\Scripts\activate

# 在 Linux/Mac 上：
source venv/bin/activate

安装依赖项：

pip install -r requirements.txt

配置环境变量：

cp .env.example .env
# 使用你的 TrueNAS 详细信息编辑 .env

获取 TrueNAS API 密钥

登录到你的 TrueNAS Core 网页界面。
导航到设置 → API 密钥。
点击添加。
为你的密钥命名（例如，“MCP 服务器”）。
点击提交。
复制生成的 API 密钥（你将无法再次查看它！）

配置

使用你的 TrueNAS 连接详细信息编辑 .env 文件：

TRUENAS_URL=https://192.168.1.100  # 你的 TrueNAS IP 地址或主机名
TRUENAS_API_KEY=1-your-api-key-here
TRUENAS_VERIFY_SSL=false  # 如果使用有效的 SSL 证书，请设置为 true

🚀 快速开始

独立模式（用于测试）

python truenas_mcp_server.py

与 Claude Desktop 配合使用

打开 Claude Desktop 设置。
导航到 MCP 服务器配置。
将以下配置添加到你的 claude_desktop_config.json 文件中：

{
  "mcpServers": {
    "truenas": {
      "command": "python",
      "args": [
        "C:\\path\\to\\truenas_mcp_server.py"
      ],
      "env": {
        "TRUENAS_URL": "https://your-truenas-ip",
        "TRUENAS_API_KEY": "your-api-key",
        "TRUENAS_VERIFY_SSL": "false"
      }
    }
  }
}

重启 Claude Desktop。

💻 使用示例

在 Claude 中的使用示例

配置完成后，你可以向 Claude 提出以下请求：

“列出我 TrueNAS 系统中的所有用户”
“显示我的存储池”
“在 'tank' 存储池中创建一个名为 'backups' 的新数据集”
“列出所有 SMB 共享”
“为 tank/data 创建一个快照”

📚 详细文档

可用功能

用户管理

list_users() - 列出系统中的所有用户
get_user(username) - 获取特定用户的详细信息

系统信息

get_system_info() - 获取 TrueNAS 系统信息

存储管理

list_pools() - 列出所有存储池
list_datasets() - 列出所有数据集
get_pool_status(pool_name) - 获取特定存储池的详细状态
create_dataset(pool, name, compression="lz4", quota=None) - 创建一个新的数据集

共享管理

list_smb_shares() - 列出所有 SMB 共享
create_smb_share(path, name, comment="", read_only=False) - 创建一个新的 SMB 共享

快照管理

create_snapshot(dataset, name, recursive=False) - 创建一个 ZFS 快照

🔧 技术细节

安全注意事项

API 密钥：确保你的 API 密钥安全，切勿将其提交到版本控制系统。
SSL 验证：在生产环境中启用 SSL 验证。
网络安全：确保你的 TrueNAS 系统仅可从受信任的网络访问。
权限：API 密钥将具有创建它的用户的相同权限。

故障排除

连接问题

验证你的 TrueNAS URL 是否正确（包括 https://）。
检查 TrueNAS 中是否启用了 API 服务。
确保你的 API 密钥有效。
如果使用自签名证书，请将 TRUENAS_VERIFY_SSL 设置为 false。

API 错误

检查 TrueNAS 日志以获取详细的错误消息。
确保你的用户具有适当的权限。
验证 API 端点与你的 TrueNAS Core 版本的兼容性。

🤝 贡献

欢迎贡献代码！请随时提交拉取请求。

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

🙏 致谢

基于 TrueNAS Core 官方 API 构建
使用了 Anthropic 的模型上下文协议（MCP）
借助 FastMCP 轻松创建 MCP 服务器

TrueNasCoreMCP