MCP Toolz

🚀 MCP Toolz

MCP Toolz 是一款强大的工具，可在 Claude Code 会话中保存上下文和待办事项，还能从 ChatGPT、Claude、Gemini 和 DeepSeek 获取反馈，助力高效开发。

🚀 快速开始

安装

从 PyPI 安装（推荐）

pip install mcp-toolz

从源代码安装（用于开发）

# 克隆仓库
git clone https://github.com/taylorleese/mcp-toolz.git
cd mcp-toolz

# 创建并激活虚拟环境
python3 -m venv venv
source venv/bin/activate  # macOS/Linux
# 或者：venv\Scripts\activate  # Windows

# 以可编辑模式安装并包含开发依赖
pip install -e ".[dev]"

配置

# 将 API 密钥设置为环境变量（AI 功能至少需要一个）
export OPENAI_API_KEY=sk-...           # 用于 ChatGPT
export ANTHROPIC_API_KEY=sk-ant-...    # 用于 Claude
export GOOGLE_API_KEY=...              # 用于 Gemini
export DEEPSEEK_API_KEY=sk-...         # 用于 DeepSeek

# 或者创建一个 .env 文件（如果从源代码安装）
cp .env.example .env
# 编辑 .env 并添加你的 API 密钥

MCP 服务器设置（推荐）

使用 mcp-toolz 的主要方式是通过 Claude Code 中的 MCP 服务器：

1. 添加到 Claude Code 设置（将此 JSON 添加到你的 Claude Code MCP 设置中）： 如果通过 pip 安装：

{
  "mcpServers": {
    "mcp-toolz": {
      "command": "python",
      "args": ["-m", "mcp_server"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "GOOGLE_API_KEY": "...",
        "DEEPSEEK_API_KEY": "sk-..."
      }
    }
  }
}

如果从源代码安装：

{
  "mcpServers": {
    "mcp-toolz": {
      "command": "python",
      "args": ["-m", "mcp_server"],
      "cwd": "/absolute/path/to/mcp-toolz",
      "env": {
        "PYTHONPATH": "/absolute/path/to/mcp-toolz/src"
      }
    }
  }
}

2. 配置 API 密钥 - 将你的 API 密钥添加到 env 部分（pip 安装）或 .env 文件（源代码安装）。
3. 重启 Claude Code 以加载 MCP 服务器。
4. 在 Claude Code 中使用 MCP 工具：
   • "Save this context about authentication"（保存有关身份验证的上下文）
   • "Ask ChatGPT about the last context I saved"（询问 ChatGPT 关于我上次保存的上下文）
   • "Show my active todos"（显示我的活动待办事项）
   • "Search contexts tagged with 'bug'"（搜索标记为 'bug' 的上下文）

所有 MCP 工具都自动可用 - 请参阅下面的 MCP 服务器工具。

✨ 主要特性

• 🔌 MCP 服务器：现已与 Claude Code 集成，实现全工具集成。
• 会话连续性：重启 Claude Code 时不会丢失上下文，可恢复“上一个会话我在做什么”。
• 项目组织：上下文和待办事项按项目目录自动组织。
• 会话跟踪：每个 Claude Code 会话都有唯一的 ID，可随时间跟踪你的工作。
• AI 反馈：从 ChatGPT（OpenAI）、Claude（Anthropic）、Gemini（Google）和 DeepSeek 获取关于你的代码和决策的反馈。
• 上下文类型：保存对话、代码片段、架构建议或错误跟踪。
• 持久待办事项：跨会话保存和恢复待办事项列表，永远不会忘记你上次的进度。
• 全文搜索：按内容、标签、项目或会话查找任何内容。
• CLI + MCP：可通过 Claude Code MCP 工具或独立的 CLI 命令使用。

📦 安装指南

从 PyPI 安装（推荐）

pip install mcp-toolz

从源代码安装（用于开发）

# 克隆仓库
git clone https://github.com/taylorleese/mcp-toolz.git
cd mcp-toolz

# 创建并激活虚拟环境
python3 -m venv venv
source venv/bin/activate  # macOS/Linux
# 或者：venv\Scripts\activate  # Windows

# 以可编辑模式安装并包含开发依赖
pip install -e ".[dev]"

💻 使用示例

基础用法

这里是在 Claude Code 中使用 mcp-toolz 的实际示例：

示例 1：获取多个 AI 对架构决策的观点

提示：

I'm deciding between using Redis or Memcached for caching user sessions.
Save this as a context and ask ChatGPT for their analysis.
Use tags: caching, redis, memcached, architecture

发生的事情：

1. Claude Code 使用 context_save 保存你的架构决策。
2. 然后使用 ask_chatgpt 获取 ChatGPT 的观点。
3. 你可以比较多个 AI 的观点以做出决策。 后续提示：

• "Ask Claude the same question for comparison"（询问 Claude 同样的问题以进行比较）
• "Ask Gemini for another perspective"（询问 Gemini 另一种观点）
• "What does DeepSeek think about this?"（DeepSeek 对此有什么看法？）
• "Search my contexts tagged with 'architecture'"（搜索我标记为 'architecture' 的上下文）

示例 2：会话连续性 - 永不丢失进度

提示（工作会话结束时）：

Save my current todo list so I can restore it tomorrow

发生的事情：

1. Claude Code 使用 todo_save 快照你当前的工作状态。
2. 待办事项与项目路径和时间戳一起保存。 第二天的提示：

What was I working on yesterday? Restore my todos.

发生的事情：

1. Claude Code 使用 todo_restore 获取你上次的快照。
2. 显示你确切的进度。
3. 你可以立即继续工作。

示例 3：使用多个 AI 观点进行调试

提示：

I'm getting "TypeError: Cannot read property 'map' of undefined" in my React component.
The error occurs in UserList.jsx when rendering the users array.
Save this as an error context and ask ChatGPT, Claude, and Gemini for debugging suggestions.
Tags: react, debugging, javascript

发生的事情：

1. Claude Code 使用 context_save 记录错误。
2. 使用 ask_chatgpt 获取 OpenAI 的调试方法。
3. 使用 ask_claude 获取 Anthropic 的观点。
4. 使用 ask_gemini 获取 Google 的分析。
5. 你可以比较多个 AI 模型的不同调试策略。 后续提示：

• "Search for other contexts tagged with 'react' bugs"（搜索其他标记为 'react' 错误的上下文）
• "Show me contexts from my last session"（显示我上一个会话的上下文）

示例 4：跟踪性能优化想法

提示：

Save this performance optimization idea: "Lazy load images below the fold using
Intersection Observer API. Estimated 40% reduction in initial page load."
Type: suggestion, Tags: performance, optimization, images

发生的事情：

1. Claude Code 使用 context_save 保存类型为 "suggestion" 的上下文。
2. 上下文可搜索并与当前项目关联。
3. 在所有未来会话中可用。 稍后的提示：

Search my contexts for performance optimization ideas

发生的事情：

1. Claude Code 使用 context_search 执行你的查询。
2. 返回跨会话的所有匹配上下文。
3. 你可以回顾过去的优化想法。

示例 5：跨会话知识共享

提示（在项目 A 中）：

I figured out how to handle OAuth refresh tokens properly.
Save this so I can reference it in other projects:
"Store refresh tokens in httpOnly cookies, access tokens in memory only.
Rotate refresh tokens on each use. Set 7-day expiry on refresh, 15min on access."
Type: code, Tags: oauth, security, authentication

提示（稍后在项目 B 中）：

How did I implement OAuth refresh tokens in my last project?
Search for contexts about oauth and show me what I saved.

发生的事情：

1. Claude Code 使用 context_search 查找你的 OAuth 实现。
2. 跨项目检索上下文。
3. 你可以重用自己的知识，无需从头开始。

高级用法

共享上下文

mcp-toolz 使跨多个 Claude Code 会话或代理共享上下文和待办事项变得容易。

MCP 资源（被动发现）

Claude Code 可以通过 MCP 资源自动发现和读取上下文/待办事项： 上下文资源：

• mcp-toolz://contexts/project/recent - 当前项目的最近上下文
• mcp-toolz://contexts/project/sessions - 当前项目的最近 Claude Code 会话列表
• mcp-toolz://contexts/session/{session_id} - 特定会话的所有上下文 待办事项资源：
• mcp-toolz://todos/recent - 最近 20 个待办事项快照（所有项目）
• mcp-toolz://todos/active - 当前工作目录的活动待办事项 会话跟踪： 通过 MCP 工具保存上下文时，它们会自动标记为：
• 当前项目目录 (project_path)
• 会话 ID（每个 Claude Code 会话唯一）
• 会话时间戳（会话开始时）

未来： 一旦 ChatGPT Desktop 添加 MCP 支持，你也可以在那里使用这些相同的工具。

共享数据库设置

默认情况下，mcp-toolz 将所有数据存储在 ~/.mcp-toolz/contexts.db 中，该数据库会自动在同一台机器上的所有项目之间共享，无需额外配置！ 对于高级用例（通过 Dropbox、iCloud 等在多台机器上同步）：

1. 选择数据库的同步位置：

# 示例：使用同步文件夹（Dropbox、iCloud、网络驱动器）
mkdir -p ~/Dropbox/mcp-toolz-shared

2. 更新 .env 文件 或 MCP 配置以指向同步数据库：

# 在 .env 文件中
MCP_TOOLZ_DB_PATH=~/Dropbox/mcp-toolz-shared/contexts.db

或者在你的 MCP 配置中：

{
  "mcpServers": {
    "mcp-toolz": {
      "command": "python",
      "args": ["-m", "mcp_server"],
      "cwd": "/absolute/path/to/mcp-toolz",
      "env": {
        "PYTHONPATH": "/absolute/path/to/mcp-toolz/src",
        "MCP_TOOLZ_DB_PATH": "/Users/you/Dropbox/mcp-toolz-shared/contexts.db"
      }
    }
  }
}

3. 重启 Claude Code - 它现在使用同步数据库位置。

工作原理

• 上下文：按 project_path 组织（每个目录有自己的上下文）
• 会话跟踪：上下文标记有会话 ID 和时间戳，便于恢复
• 待办事项：按 project_path 组织（每个目录有自己的快照）
• 单个 SQLite 数据库：所有数据存储在一个数据库中，按项目和会话过滤
• 自动更新：一个会话中所做的更改会立即对其他会话可见

使用案例

• 多台机器：在笔记本电脑和台式机之间保持上下文同步。
• 会话连续性：在重启 Claude Code 后继续你上次的工作。

CLI 使用（可选）

# 获取 ChatGPT 对某件事的意见
./mcp-toolz context save-and-query \
  --type suggestion \
  --title "Redis caching strategy" \
  --content "Use Redis for session storage with 1-hour TTL" \
  --tags "caching,redis"

# 保存你当前的待办事项
./mcp-toolz todo save \
  --todos '[
    {"content":"Fix auth bug","status":"in_progress","activeForm":"Fixing auth bug"},
    {"content":"Write tests","status":"pending","activeForm":"Writing tests"}
  ]' \
  --context "Working on authentication"

# 列出所有内容
./mcp-toolz context list
./mcp-toolz todo list

# 稍后恢复待办事项
./mcp-toolz todo restore

📚 详细文档

MCP 服务器工具

MCP 服务器现已与 Claude Code 集成，并提供以下工具： 上下文工具：

• context_save - 保存新上下文（自动包含会话信息）
• context_search - 按查询或标签搜索
• context_get - 按 ID 获取
• context_list - 列出最近的
• context_delete - 按 ID 删除 AI 反馈工具：
• ask_chatgpt - 获取 ChatGPT 对上下文的分析（支持自定义问题）
• ask_claude - 获取 Claude 对上下文的分析（支持自定义问题）
• ask_gemini - 获取 Gemini 对上下文的分析（支持自定义问题）
• ask_deepseek - 获取 DeepSeek 对上下文的分析（支持自定义问题） 待办事项工具：
• todo_search - 搜索快照
• todo_get - 按 ID 获取
• todo_list - 列出最近的
• todo_save - 保存快照
• todo_restore - 获取活动/特定快照
• todo_delete - 按 ID 删除 会话跟踪： 通过 MCP 工具保存上下文时，它们会自动标记为：
• 当前项目目录 (project_path)
• 会话 ID（每个 Claude Code 会话唯一）
• 会话时间戳（会话开始时）

命令参考

上下文命令

# 保存并立即查询 ChatGPT
./mcp-toolz context save-and-query \
  --type <type> \
  --title "Title" \
  --content "..." \
  --tags "tag1,tag2"

# 保存但不查询
./mcp-toolz context save --type code --file path/to/file.py

# 询问 ChatGPT 或 Claude 关于现有上下文
./mcp-toolz context ask-chatgpt <context-id> [--question "Your question"]
./mcp-toolz context ask-claude <context-id> [--question "Your question"]

# 浏览和搜索
./mcp-toolz context list [--limit N] [--type TYPE]
./mcp-toolz context search "query"
./mcp-toolz context show <context-id>

# 删除
./mcp-toolz context delete <context-id>

上下文类型：

• suggestion - 架构决策、实施计划
• code - 代码片段、实现
• conversation - 讨论、问答会话
• error - 错误消息、堆栈跟踪、调试

待办事项命令

# 保存当前待办事项
./mcp-toolz todo save \
  --todos '[{"content":"...","status":"pending","activeForm":"..."}]' \
  --context "What you're working on"

# 恢复（默认为当前项目的活动快照）
./mcp-toolz todo restore [<snapshot-id>]

# 浏览和搜索
./mcp-toolz todo list [--project-path PATH]
./mcp-toolz todo search "query"
./mcp-toolz todo show <snapshot-id>

# 删除
./mcp-toolz todo delete <snapshot-id>

待办事项状态： pending（待办）、in_progress（进行中）、completed（已完成）

获取帮助

./mcp-toolz --help
./mcp-toolz context --help
./mcp-toolz todo --help

常见工作流程

获取多个 AI 观点

在评估实现方案时，比较不同 AI 模型的见解：

./mcp-toolz context save-and-query \
  --type suggestion \
  --title "Microservices vs Monolith for e-commerce" \
  --content "Building platform with 5 services. Start microservices or monolith first?" \
  --tags "architecture,scalability"

AI 的响应会立即显示在你的控制台中。你还可以询问特定问题或获取 Claude 的观点：

# 询问关于上下文的特定问题
./mcp-toolz context ask-chatgpt <context-id> --question "What are the scalability concerns?"

# 获取 Claude 的一般意见
./mcp-toolz context ask-claude <context-id>

# 或者询问 Claude 特定问题
./mcp-toolz context ask-claude <context-id> --question "How would you handle database migrations?"

用两种观点进行调试

./mcp-toolz context save-and-query \
  --type error \
  --title "CORS issue in production" \
  --content "Error: blocked by CORS policy. Headers: ..." \
  --tags "debugging,cors,production"

会话连续性

# 工作会话结束时
./mcp-toolz todo save \
  --todos '[
    {"content":"Implement login","status":"completed","activeForm":"Implementing login"},
    {"content":"Add OAuth","status":"in_progress","activeForm":"Adding OAuth"},
    {"content":"Write tests","status":"pending","activeForm":"Writing tests"}
  ]' \
  --context "Day 2 of auth feature"

# 下一个会话
./mcp-toolz todo restore

跨 Claude Code 会话共享

# 会话 1：保存有趣的讨论
./mcp-toolz context save \
  --type conversation \
  --title "Performance optimization ideas" \
  --content "..." \
  --tags "performance"

# 会话 2：查找并查看
./mcp-toolz context search "performance"
./mcp-toolz context show <context-id>

# 或者询问 AI 特定问题
./mcp-toolz context ask-chatgpt <context-id> --question "What's the performance impact?"
./mcp-toolz context ask-claude <context-id> --question "Are there any security concerns?"

环境变量

# 必需（AI 功能至少需要一个）
OPENAI_API_KEY=sk-...                              # 你的 OpenAI API 密钥
ANTHROPIC_API_KEY=sk-ant-...                       # 你的 Anthropic API 密钥
GOOGLE_API_KEY=...                                 # 你的 Google API 密钥（用于 Gemini）
DEEPSEEK_API_KEY=sk-...                            # 你的 DeepSeek API 密钥

# 可选
MCP_TOOLZ_DB_PATH=~/.mcp-toolz/contexts.db                    # 共享数据库位置（默认）
MCP_TOOLZ_MODEL=gpt-5                                         # OpenAI 模型（默认：gpt-5）
MCP_TOOLZ_CLAUDE_MODEL=claude-sonnet-4-5-20250929             # Claude 模型
MCP_TOOLZ_GEMINI_MODEL=gemini-2.0-flash-thinking-exp-01-21   # Gemini 模型
MCP_TOOLZ_DEEPSEEK_MODEL=deepseek-chat                        # DeepSeek 模型

故障排除

"Error 401: Invalid API key"

• 验证 API 密钥是否设置在 .env 中（OPENAI_API_KEY 和/或 ANTHROPIC_API_KEY）。
• 检查你的 OpenAI/Anthropic 账户是否启用了计费。
• ./mcp-toolz 包装器会自动取消设置 shell 环境变量以使用 .env。

"No module named context_manager"

• 使用 ./mcp-toolz 辅助脚本（推荐）。
• 或者在直接运行 Python 之前设置 PYTHONPATH=src。

命令未找到

• 激活虚拟环境：source venv/bin/activate。
• 使脚本可执行：chmod +x mcp-toolz。

待办事项无法恢复

• 检查你是否在同一项目目录中。
• 使用 ./mcp-toolz todo list 查看所有快照。
• 恢复特定快照：./mcp-toolz todo restore <snapshot-id>。

🔧 技术细节

项目结构

mcp-toolz/
├── src/
│   ├── mcp_server/          # Claude Code 的 MCP 服务器
│   │   └── server.py        # MCP 工具和资源
│   ├── context_manager/     # CLI 和存储
│   │   ├── cli.py          # 基于 Click 的 CLI
│   │   ├── storage.py      # SQLite 操作
│   │   ├── openai_client.py # ChatGPT API 客户端
│   │   └── anthropic_client.py # Claude API 客户端
│   └── models.py           # Pydantic 数据模型
├── data/
│   └── contexts.db         # SQLite 数据库
├── requirements.txt
├── requirements-dev.txt
└── mcp-toolz               # 辅助脚本

开发

贡献者设置

# 克隆并安装
git clone https://github.com/taylorleese/mcp-toolz.git
cd mcp-toolz
python3 -m venv venv
source venv/bin/activate
pip install -r requirements-dev.txt

# 安装 pre-commit 钩子（重要！）
pre-commit install

# 复制并配置 .env
cp .env.example .env
# 编辑 .env 并添加你的 API 密钥

运行测试

source venv/bin/activate
pytest

代码质量

# 运行所有检查（在安装 pre-commit 后提交时自动运行）
pre-commit run --all-files

# 单个工具
black .
ruff check .
mypy src/

📄 许可证

本项目采用 MIT 许可证。

💡 使用建议

1. 使用描述性标题 - 方便后续搜索。
2. 添加相关标签 - 有助于组织和查找上下文。
3. 内容具体 - 更多细节 = 更好的 AI 响应。
4. 比较 AI 意见 - 在重要决策上同时获取 ChatGPT 和 Claude 的观点。
5. 审查 AI 建议 - 它们是有用的意见，而非规则。
6. 定期保存待办事项 - 养成在会话结束时保存的习惯。