mcp-toolbox

一个通过模型上下文协议 (MCP) 增强 LLM 功能的综合工具包。此软件包提供了一系列工具，使 LLM 能够与外部服务和 API 交互，从而将其功能扩展到文本生成之外。

• GitHub 仓库: https://github.com/ai-zerolab/mcp-toolbox/
• (WIP)文档: 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  # For macOS/Linux
# 或
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"  # For Windows

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

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

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

通过 Smithery 安装

要通过 Smithery 自动安装用于 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	通过 key 获取 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	通过 key 获取组件
figma_get_team_component_sets	获取团队的组件集
figma_get_team_styles	获取团队的样式
figma_get_file_styles	获取文件的样式
figma_get_style	通过 key 获取样式

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

Web 工具

工具	描述
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 处理 Web 内容：
   • "从 https://example.com 获取 HTML 内容"
   • "将 https://example.com 的 HTML 保存到文件"
   • "在网上搜索 '人工智能新闻'"
9. 要求 Claude 使用 Flux 生成图像：
   • "生成一张山脉上美丽的日落的图像"
   • "创建一张未来城市的图像并将其保存到我的桌面"
   • "生成一张穿着太空服的猫的肖像"
10. 要求 Claude 使用内存工具：
    • "记住这个重要的事实：法国的首都是巴黎"
    • "我当前的会话 ID 是什么？"
    • "回忆任何关于法国的信息"
    • "思考气候变化的影响"
    • "忘记所有存储的记忆"

开发

本地设置

Fork 仓库并将其克隆到您的本地计算机。

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

运行测试

make test

运行检查

make check

构建文档

make docs

添加新工具

要添加新的 API 集成：

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

有关更详细的说明，请参阅开发指南。

贡献

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

1. Fork 仓库
2. 创建一个功能分支 (git checkout -b feature/amazing-feature)
3. 提交您的更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开一个 Pull Request

许可证

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