mcp-toolbox

通过模型上下文协议（MCP）增强大型语言模型（LLM）能力的综合工具包。此包提供了一系列工具，使LLM能够与外部服务和API交互，扩展其功能远超文本生成。

• GitHub仓库：https://github.com/ai-zerolab/mcp-toolbox/
• (进行中)文档：https://ai-zerolab.github.io/mcp-toolbox/

特性

*nix是我们主要的目标平台，但Windows也应该可以工作。

• 命令行执行：通过LLM执行任何命令行指令。
• Figma集成：访问Figma文件、组件、样式等。
• 可扩展架构：轻松添加新的API集成。
• MCP协议支持：兼容Claude Desktop和其他启用MCP的LLM。
• 全面测试：具有高测试覆盖率的经过充分测试的代码库。

安装

使用uv（推荐）

我们推荐使用uv来管理您的环境。

# 安装uv
curl -LsSf https://astral.sh/uv/install.sh | sh  # 对于macOS/Linux
# 或者
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"  # 对于Windows

然后您可以使用uvx "mcp-toolbox@latest" stdio作为命令来运行最新版本的MCP服务器。音频和内存工具不包括在默认安装中，您可以通过安装all额外项来包含它们：

[audio]用于音频工具，[memory]用于内存工具，[all]用于所有工具

uvx "mcp-toolbox[all]@latest" stdio

通过Smithery安装

要自动通过Smithery安装Toolbox以增强Claude Desktop的LLM：

npx -y @smithery/cli install @ai-zerolab/mcp-toolbox --client claude

使用pip

pip install "mcp-toolbox[all]"

然后您可以使用mcp-toolbox stdio作为命令来运行MCP服务器。

配置

环境变量

可以配置以下环境变量：

• FIGMA_API_KEY：Figma集成的API密钥
• TAVILY_API_KEY：Tavily集成的API密钥
• DUCKDUCKGO_API_KEY：DuckDuckGo集成的API密钥
• BFL_API_KEY：Flux图像生成API的API密钥

内存存储

内存工具将数据存储在以下位置：

• macOS：~/Documents/zerolab/mcp-toolbox/memory（通过iCloud同步设备）
• 其他平台：~/.zerolab/mcp-toolbox/memory

完整配置

要使用mcp-toolbox与Claude Desktop/Cline/Cursor/...，请在配置文件中添加以下内容：

{
  "mcpServers": {
    "zerolab-toolbox": {
      "command": "uvx",
      "args": ["--prerelease=allow", "mcp-toolbox@latest", "stdio"],
      "env": {
        "FIGMA_API_KEY": "your-figma-api-key",
        "TAVILY_API_KEY": "your-tavily-api-key",
        "DUCKDUCKGO_API_KEY": "your-duckduckgo-api-key",
        "BFL_API_KEY": "your-bfl-api-key"
      }
    }
  }
}

对于全部特性：

{
  "mcpServers": {
    "zerolab-toolbox": {
      "command": "uvx",
      "args": [
        "--prerelease=allow",
        "--python=3.12",
        "mcp-toolbox[all]@latest",
        "stdio"
      ],
      "env": {
        "FIGMA_API_KEY": "your-figma-api-key",
        "TAVILY_API_KEY": "your-tavily-api-key",
        "DUCKDUCKGO_API_KEY": "your-duckduckgo-api-key",
        "BFL_API_KEY": "your-bfl-api-key"
      }
    }
  }
}

您可以使用以下命令生成调试配置模板：

uv run generate_config_template.py

可用工具

命令行工具

工具	描述
execute_command	执行一个命令行指令

文件操作工具

工具	描述
read_file_content	从文件读取内容
write_file_content	将内容写入文件
replace_in_file	使用正则表达式替换文件中的内容
list_directory	列出目录内容并提供详细信息

Figma工具

工具	描述
figma_get_file	根据键获取Figma文件
figma_get_file_nodes	获取Figma文件中的特定节点
figma_get_image	获取Figma文件中节点的图片
figma_get_image_fills`	获取Figma文件中使用的图片的URL
figma_get_comments	获取Figma文件上的评论
figma_post_comment	在Figma文件上发布评论
figma_delete_comment	删除Figma文件上的评论
figma_get_team_projects	获取团队项目
figma_get_project_files	获取项目的文件
figma_get_team_components	获取团队组件
figma_get_file_components	从文件获取组件
figma_get_component	根据键获取组件
figma_get_team_component_sets	获取团队组件集
figma_get_team_styles	获取团队样式
figma_get_file_styles	从文件获取样式
figma_get_style	根据键获取样式

XiaoyuZhouFM工具

工具	描述
xiaoyuzhoufm_download	从XiaoyuZhouFM下载播客剧集，可选自动将m4a转换为mp3

音频工具

工具	描述
get_audio_length	获取音频文件的长度（秒）
get_audio_text	从音频文件的特定时间范围内获取转录文本

内存工具

工具	描述
think	使用该工具思考某事并将想法追加到日志中
get_session_id	获取当前会话ID
remember	将记忆（简短和详细）存储在记忆数据库中
recall	使用语义搜索从数据库查询记忆
forget	清除记忆数据库中的所有记忆

Markitdown工具

工具	描述
convert_file_to_markdown	使用MarkItDown将任何文件转换为Markdown
convert_url_to_markdown	使用MarkItDown将URL转换为Markdown

网络工具

工具	描述
get_html	从URL获取HTML内容
save_html	将URL的HTML保存到文件中
search_with_tavily	使用Tavily搜索网络（需要API密钥）
search_with_duckduckgo	使用DuckDuckGo搜索网络（需要API密钥）

Flux图像生成工具

工具	描述
flux_generate_image	使用Flux API生成图像并将其保存到文件中

使用示例

运行MCP服务器

# 使用stdio传输运行（默认）
mcp-toolbox stdio

# 使用SSE传输运行
mcp-toolbox sse --host localhost --port  9871

与Claude Desktop一起使用

1. 按照配置部分所示配置Claude Desktop
2. 启动Claude Desktop
3. 请求Claude与Figma文件互动：
   • "你能获取这个Figma文件的信息吗：12345abcde？"
   • "显示这个Figma文件中的组件：12345abcde"
   • "获取这个Figma文件的评论：12345abcde"
4. 请求Claude执行命令行指令：
   • "当前目录中有哪些文件？"
   • "当前系统时间是什么？"
   • "显示某个特定文件的内容。"
5. 请求Claude从XiaoyuZhouFM下载播客：
   • "下载这个播客剧集：https://www.xiaoyuzhoufm.com/episode/67c3d80fb0167b8db9e3ec0f"
   • "下载并转换为MP3这个播客：https://www.xiaoyuzhoufm.com/episode/67c3d80fb0167b8db9e3ec0f"
6. 请求Claude处理音频文件：
   • "这个音频文件的长度是多少：audio.m4a？"
   • "转录audio.m4a从60秒到90秒的音频"
   • "获取音频文件从2:30到3:00的文本"
7. 请求Claude将文件或URL转换为Markdown：
   • "将这个文件转换为Markdown：document.docx"
   • "将这个网页转换为Markdown：https://example.com"
8. 请求Claude处理网络内容：
   • "从https://example.com获取HTML内容"
   • "将https://example.com的HTML保存到文件中"
   • "搜索关于‘人工智能新闻’的网络内容"
9. 请求Claude生成图像：
   • "生成一幅美丽的落日山景图"
   • "创建一幅未来城市的图像并将其保存到我的桌面上"
   • "生成一幅穿着太空服的猫的肖像"
10. 请求Claude使用记忆工具：
    • "记住这个重要事实：法国的首都是巴黎"
    • "我的当前会话ID是什么？"
    • "回忆有关法国的任何信息"
    • "思考气候变化的影响"
    • "忘记所有存储的记忆"

开发

本地设置

分叉仓库并将其克隆到您的本地机器。

# 以开发模式安装
make install
# 激活虚拟环境
source .venv/bin/activate  # 对于macOS/Linux
# 或者
.venv\Scripts\activate  # 对于Windows

运行测试

make test

运行检查

make check

构建文档

make docs

添加新工具

要添加一个新的API集成：

1. 更新config.py以包含所需的API密钥
2. 在mcp_toolbox/中创建一个新的模块
3. 实现您的API客户端和工具
4. 为新功能编写测试
5. 更新README.md以包含新的环境变量和工具

请参阅开发指南以获取更详细的说明。

贡献

欢迎贡献！请随意提交Pull Request。

1. 分叉仓库
2. 创建一个功能分支（git checkout -b feature/amazing-feature）
3. 提交您的更改（git commit -m '添加一些惊人的功能'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 打开一个Pull Request

许可证

本项目根据仓库中包含的许可证条款进行许可。