STARWARCLOUD STARWAR.AI
返回市场
真纳斯核心MCP

真纳斯核心MCP

作者：vespo926 星标更新：2025-11-23
安装使用来源：spider==github.com

项目介绍

TrueNAS MCP 服务器

Python 版本 MCP 版本 许可证 PyPI 版本

适用于 TrueNAS 核心系统的生产就绪型模型上下文协议（MCP）服务器。通过自然语言与 Claude 或其他兼容 MCP 的客户端控制和管理您的 TrueNAS 存储。

🚀 功能

核心功能

  • 用户管理 - 创建、更新、删除用户并管理权限
  • 存储管理 - 管理池、数据集、卷，并支持完整的 ZFS 功能
  • 文件共享 - 配置 SMB、NFS 和 iSCSI 共享
  • 快照管理 - 创建、删除、回滚快照，并支持自动化
  • 系统监控 - 检查系统健康状况、池状态和资源使用情况

企业功能

  • 类型安全操作 - 完整的 Pydantic 模型用于请求/响应验证
  • 全面错误处理 - 提供详细的错误消息和恢复指导
  • 生产日志记录 - 结构化日志记录，具有可配置的日志级别
  • 连接池 - 使用重试逻辑高效管理 HTTP 连接
  • 速率限制 - 内置速率限制以防止 API 被滥用
  • 基于环境的配置 - 通过环境变量进行灵活配置

📦 安装

使用 uvx 快速启动（推荐）

运行 TrueNAS MCP 服务器最简单的方法是使用 uvx：

# 直接运行无需安装
uvx truenas-mcp-server

# 或者全局安装 uv
uv tool install truenas-mcp-server

传统安装

# 使用 pip
pip install truenas-mcp-server

# 或者使用 pipx 创建隔离环境
pipx install truenas-mcp-server

从源码安装

git clone https://github.com/vespo92/TrueNasCoreMCP.git
cd TrueNasCoreMCP
pip install -e .

🔧 配置

环境变量

创建一个 .env 文件或设置环境变量：

# 必需
TRUENAS_URL=https://your-truenas-server.local
TRUENAS_API_KEY=your-api-key-here

# 可选
TRUENAS_VERIFY_SSL=true                    # 验证 SSL 证书
TRUENAS_LOG_LEVEL=INFO                     # 日志级别
TRUENAS_ENV=production                     # 环境（开发/测试/生产）
TRUENAS_HTTP_TIMEOUT=30                    # HTTP 超时时间（秒）
TRUENAS_ENABLE_DESTRUCTIVE_OPS=false      # 启用删除操作
TRUENAS_ENABLE_DEBUG_TOOLS=false          # 启用调试工具

获取 API 密钥

  1. 登录到 TrueNAS Web UI
  2. 前往 设置 → API 密钥
  3. 点击 添加 并创建一个新的 API 密钥
  4. 立即复制密钥（它不会再次显示）

Claude Desktop 配置

添加到您的 Claude Desktop 配置 (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 环境。确保您已安装 uv：

# 如果尚未安装，请安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# 或者
brew install uv

📚 使用示例

使用 Claude Desktop

配置完成后，您可以使用自然语言与 TrueNAS 进行交互：

"列出所有存储池及其健康状态"
"在 tank 池中创建名为 'backups' 的新数据集，并启用压缩"
"为 documents 数据集设置 SMB 共享"
"创建 tank 池中所有数据集的快照"
"显示具有 sudo 权限的用户"

作为 Python 库

from truenas_mcp_server import TrueNASMCPServer

# 创建服务器实例
server = TrueNASMCPServer()

# 运行服务器
server.run()

程序化使用

import asyncio
from truenas_mcp_server.client import TrueNASClient
from truenas_mcp_server.config import Settings

async def main():
    # 初始化客户端
    settings = Settings(
        truenas_url="https://truenas.local",
        truenas_api_key="your-api-key"
    )
    
    async with TrueNASClient(settings) as client:
        # 列出池
        pools = await client.get("/pool")
        print(f"找到 {len(pools)} 个池")
        
        # 创建数据集
        dataset = await client.post("/pool/dataset", {
            "name": "tank/mydata",
            "compression": "lz4"
        })
        print(f"创建数据集：{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 - 设置自动快照

调试工具（开发模式）

  • debug_connection - 检查连接设置
  • test_connection - 验证 API 连接性
  • get_server_stats - 服务器统计信息

🏗️ 架构

truenas_mcp_server/
├── __init__.py           # 包初始化
├── server.py             # 主 MCP 服务器
├── config/               # 配置管理
│   ├── __init__.py
│   └── settings.py       # Pydantic 设置
├── client/               # HTTP 客户端
│   ├── __init__.py
│   └── http_client.py    # 异步 HTTP 重试
├── models/               # 数据模型
│   ├── __init__.py
│   ├── base.py          # 基础模型
│   ├── user.py          # 用户模型
│   ├── storage.py       # 存储模型
│   └── sharing.py       # 共享模型
├── tools/                # MCP 工具
│   ├── __init__.py
│   ├── base.py          # 基础工具类
│   ├── users.py         # 用户工具
│   ├── storage.py       # 存储工具
│   ├── sharing.py       # 共享工具
│   └── snapshots.py     # 快照工具
└── exceptions.py         # 自定义异常

🧪 开发

设置开发环境

# 克隆仓库
git clone https://github.com/vespo92/TrueNasCoreMCP.git
cd TrueNasCoreMCP

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # 在 Windows 上：venv\Scripts\activate

# 开发模式安装
pip install -e ".[dev]"

运行测试

# 运行所有测试
pytest

# 带覆盖率
pytest --cov=truenas_mcp_server

# 特定测试文件
pytest tests/test_client.py

代码质量

# 格式化代码
black truenas_mcp_server

# 代码检查
flake8 truenas_mcp_server

# 类型检查
mypy truenas_mcp_server

📖 文档

🤝 贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解指南。

  1. 分叉仓库
  2. 创建功能分支 (git checkout -b feature/amazing-feature)
  3. 提交更改 (git commit -m '添加神奇功能')
  4. 推送到分支 (git push origin feature/amazing-feature)
  5. 打开拉取请求

📝 许可证

此项目采用 MIT 许可证 - 详情见 LICENSE 文件。

🔒 安全

  • 不要提交 API 密钥或凭据
  • 使用环境变量存储敏感数据
  • 生产环境中启用 SSL 验证
  • 默认情况下限制破坏性操作
  • 通过 GitHub Issues 报告安全问题

📞 支持

🙏 致谢

为 TrueNAS 社区制作 ❤️