Truenascoremcp

🚀 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 密钥

安装步骤

1. 克隆此仓库：

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

2. 创建虚拟环境：

python -m venv venv

# 在 Windows 上：
venv\Scripts\activate

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

3. 安装依赖项：

pip install -r requirements.txt

4. 配置环境变量：

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

获取 TrueNAS API 密钥

1. 登录到你的 TrueNAS Core 网页界面。
2. 导航到 设置 → API 密钥。
3. 点击 添加。
4. 为你的密钥命名（例如，“MCP 服务器”）。
5. 点击 提交。
6. 复制生成的 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 配合使用

1. 打开 Claude Desktop 设置。
2. 导航到 MCP 服务器配置。
3. 将以下配置添加到你的 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"
      }
    }
  }
}

4. 重启 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 服务器