真纳斯核心MCP

Name: 真纳斯核心MCP
Author: vespo92

作者：vespo926 星标更新：2025-11-23

安装使用来源：spider==github.com

项目介绍

TrueNAS MCP 服务器

适用于 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 密钥

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

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

📖 文档

安装指南 - 详细的安装说明
快速开始 - 快速上手
快速参考 - 命令参考
功能概述 - 详细的特性文档
API 文档 - 即将推出

🤝 贡献

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

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

📝 许可证

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

🔒 安全

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

📞 支持

问题：GitHub Issues
讨论：GitHub Discussions

🙏 致谢

Anthropic 提供 MCP 规范
TrueNAS 提供卓越的存储平台
MCP Python SDK 贡献者

为 TrueNAS 社区制作 ❤️