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 来管理您的环境。

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh  # For macOS/Linux
# or
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安装Toolbox for LLM Enhancement：

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服务器

# Run with stdio transport (default)
mcp-toolbox stdio

# Run with SSE transport
mcp-toolbox sse --host localhost --port 9871

与Claude桌面版一起使用

1. 按照配置部分所示配置 Claude Desktop
2. 启动 Claude Desktop
3. 要求 Claude 与 Figma 文件交互：
   • "你能获取这个 Figma 文件的信息吗：12345abcde？"
   • "显示这个 Figma 文件中的组件：12345abcde"
   • "从这个 Figma 文件中获取评论：12345abcde"
4. 要求 Claude 执行命令行指令：
   • "当前目录下有哪些文件？"
   • "当前系统时间是多少？"
   • "显示特定文件的内容。"
5. 要求 Claude 从小宇宙FM下载播客：
   • "下载这集播客：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 将文件或网址转换为 Markdown：
   • "将此文件转换为 Markdown：document.docx"
   • "将此网页转换为 Markdown：https://example.com"
8. 要求 Claude 处理网络内容：
   • "从 https://example.com 获取 HTML 内容"
   • "将 https://example.com 的 HTML 保存到文件"
   • "在网络上搜索'人工智能新闻'"
9. 要求 Claude 使用 Flux 生成图像：
   • "生成一张美丽的山景日落图片"
   • "创建一张未来城市的图片并保存到我的桌面"
   • "生成一只穿着太空服的猫的肖像"
10. 要求 Claude 使用记忆工具：
    • "记住这个重要事实：法国的首都是巴黎"
    • "我当前的会话ID是什么？"
    • "回忆关于法国的任何信息"
    • "思考气候变化的影响"
    • "忘记所有存储的记忆"

开发

本地设置

分叉仓库并将它克隆到你的本地机器。

# Install in development mode
make install
# Activate a virtual environment
source .venv/bin/activate  # For macOS/Linux
# or
.venv\Scripts\activate  # For 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 'Add some amazing feature'）
4. 推送到该分支（git push origin feature/amazing-feature）
5. 打开 Pull Request

许可证

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