# MCP Toolz
mcp-name: io.github.taylorleese/mcp-toolz
[](https://github.com/taylorleese/mcp-toolz/actions/workflows/ci.yml)
[](https://github.com/taylorleese/mcp-toolz/issues)
[](https://github.com/taylorleese/mcp-toolz/commits/main)
[](https://codecov.io/gh/taylorleese/mcp-toolz)
[](https://pypi.org/project/mcp-toolz/)
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io)
[](https://opensource.org/licenses/MIT)
[](https://github.com/pre-commit/pre-commit)
[](https://www.bestpractices.dev/projects/11358)
[](https://scorecard.dev/viewer/?uri=github.com/taylorleese/mcp-toolz)
[](https://github.com/taylorleese/mcp-toolz/blob/main/.github/dependabot.yml)
MCP server for Claude Code providing context management, todo persistence, and multi-AI perspectives. Share contexts and todos across sessions, compare insights from ChatGPT, Claude, Gemini, and DeepSeek, and access everything via MCP tools.
## Features
- **🔌 MCP Server**: Works NOW with Claude Code - full tool integration ready
- **Session Continuity**: Never lose context when restarting Claude Code - restore "what was I working on last session"
- **Project Organization**: Contexts and todos automatically organized by project directory
- **Session Tracking**: Every Claude Code session gets a unique ID - track your work over time
- **Multi-AI Perspectives**: Compare feedback from ChatGPT (OpenAI), Claude (Anthropic), Gemini (Google), and DeepSeek on your code and decisions
- **Context Types**: Save conversations, code snippets, architectural suggestions, or error traces
- **Persistent Todos**: Save and restore your todo list across sessions - never forget where you left off
- **Full-Text Search**: Find anything by content, tags, project, or session
- **CLI + MCP**: Use via Claude Code MCP tools or standalone CLI commands
## Quick Start
### Installation
#### From PyPI (Recommended)
```bash
pip install mcp-toolz
```
#### From Source (Development)
```bash
# Clone the repository
git clone https://github.com/taylorleese/mcp-toolz.git
cd mcp-toolz
# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate # macOS/Linux
# or: venv\Scripts\activate # Windows
# Install in editable mode with dev dependencies
pip install -e ".[dev]"
```
### Configuration
```bash
# Set your API keys as environment variables (at least one required for AI features)
export OPENAI_API_KEY=sk-... # For ChatGPT
export ANTHROPIC_API_KEY=sk-ant-... # For Claude
export GOOGLE_API_KEY=... # For Gemini
export DEEPSEEK_API_KEY=sk-... # For DeepSeek
# Or create a .env file (if installing from source)
cp .env.example .env
# Edit .env and add your API keys
```
### MCP Server Setup (Recommended)
The primary way to use mcp-toolz is via the MCP server in Claude Code:
1. **Add to Claude Code settings** (add this JSON to your Claude Code MCP settings):
**If installed via pip:**
```json
{
"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-..."
}
}
}
}
```
**If installed from source:**
```json
{
"mcpServers": {
"mcp-toolz": {
"command": "python",
"args": ["-m", "mcp_server"],
"cwd": "/absolute/path/to/mcp-toolz",
"env": {
"PYTHONPATH": "/absolute/path/to/mcp-toolz/src"
}
}
}
}
```
2. **Configure API keys** - Add your API keys to the `env` section (pip) or `.env` file (source)
3. **Restart Claude Code** to load the MCP server
4. **Use MCP tools in Claude Code**:
- "Save this context about authentication"
- "Ask ChatGPT about the last context I saved"
- "Show my active todos"
- "Search contexts tagged with 'bug'"
All MCP tools are automatically available - see [MCP Server Tools](#mcp-server-tools) below.
## MCP Server Tools
The MCP server works NOW with Claude Code and provides these tools:
**Context Tools:**
- `context_save` - Save a new context (automatically includes session info)
- `context_search` - Search by query or tags
- `context_get` - Get by ID
- `context_list` - List recent
- `context_delete` - Delete by ID
**Multi-AI Perspective Tools:**
- `ask_chatgpt` - Get ChatGPT's analysis of a context (supports custom questions)
- `ask_claude` - Get Claude's analysis of a context (supports custom questions)
- `ask_gemini` - Get Gemini's analysis of a context (supports custom questions)
- `ask_deepseek` - Get DeepSeek's analysis of a context (supports custom questions)
**Todo Tools:**
- `todo_search` - Search snapshots
- `todo_get` - Get by ID
- `todo_list` - List recent
- `todo_save` - Save snapshot
- `todo_restore` - Get active/specific snapshot
- `todo_delete` - Delete by ID
**Session Tracking:**
When saving contexts through MCP tools, they are automatically tagged with:
- Current project directory (`project_path`)
- Session ID (unique per Claude Code session)
- Session timestamp (when the session started)
**Future:** Once ChatGPT Desktop adds MCP support, you'll be able to use these same tools there too.
## Usage Examples
Here are practical examples of how to use mcp-toolz in Claude Code:
### Example 1: Get Multiple AI Perspectives on Architecture Decisions
**Prompt:**
```
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
```
**What happens:**
1. Claude Code uses `context_save` to save your architectural decision
2. Then uses `ask_chatgpt` to get ChatGPT's perspective
3. You can compare multiple AI perspectives to inform your decision
**Follow-up prompts:**
- "Ask Claude the same question for comparison"
- "Ask Gemini for another perspective"
- "What does DeepSeek think about this?"
- "Search my contexts tagged with 'architecture'"
### Example 2: Session Continuity - Never Lose Your Place
**Prompt (end of work session):**
```
Save my current todo list so I can restore it tomorrow
```
**What happens:**
1. Claude Code uses `todo_save` to snapshot your current work state
2. Todos are saved with project path and timestamp
**Next day prompt:**
```
What was I working on yesterday? Restore my todos.
```
**What happens:**
1. Claude Code uses `todo_restore` to get your last snapshot
2. Shows you exactly where you left off
3. You can jump right back into work
### Example 3: Debug with Multiple AI Perspectives
**Prompt:**
```
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
```
**What happens:**
1. Claude Code uses `context_save` to record the error
2. Uses `ask_chatgpt` to get OpenAI's debugging approach
3. Uses `ask_claude` to get Anthropic's perspective
4. Uses `ask_gemini` for Google's analysis
5. You can compare different debugging strategies from multiple AI models
**Follow-up prompts:**
- "Search for other contexts tagged with 'react' bugs"
- "Show me contexts from my last session"
### Example 4: Track Performance Optimization Ideas
**Prompt:**
```
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
```
**What happens:**
1. Claude Code uses `context_save` with type "suggestion"
2. Context is searchable and tied to current project
3. Available across all future sessions
**Later prompt:**
```
Search my contexts for performance optimization ideas
```
**What happens:**
1. Claude Code uses `context_search` with your query
2. Returns all matching contexts across sessions
3. You can review past optimization ideas
### Example 5: Cross-Session Knowledge Sharing
**Prompt (in Project 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
```
**Prompt (later in Project B):**
```
How did I implement OAuth refresh tokens in my last project?
Search for contexts about oauth and show me what I saved.
```
**What happens:**
1. Claude Code uses `context_search` to find your OAuth implementation
2. Retrieves the context across projects
3. You reuse your own knowledge without starting from scratch
## Sharing Contexts Between Agents
mcp-toolz makes it easy to share contexts and todos across multiple Claude Code sessions or agents.
### MCP Resources (Passive Discovery)
Claude Code can automatically discover and read contexts/todos via MCP resources:
**Context Resources:**
- `mcp-toolz://contexts/project/recent` - Recent contexts for current project
- `mcp-toolz://contexts/project/sessions` - List of recent Claude Code sessions for current project
- `mcp-toolz://contexts/session/{session_id}` - All contexts from a specific session
**Todo Resources:**
- `mcp-toolz://todos/recent` - Last 20 todo snapshots (all projects)
- `mcp-toolz://todos/active` - Active todos for current working directory
**Session Tracking:**
Each Claude Code session automatically gets a unique session ID. All contexts saved during that session are tagged with:
- `session_id` - UUID of the Claude Code session
- `session_timestamp` - When the session started
- `project_path` - Directory where the context was created
This makes it easy to restore context from previous sessions: "Show me what I was working on in my last session"
Resources are read-only views into the shared database. Claude Code can discover them automatically without explicit tool calls.
### Shared Database Setup
**By default**, mcp-toolz stores all data in `~/.mcp-toolz/contexts.db`, which is automatically shared across all projects on the same machine. No additional configuration needed!
**For advanced use cases** (syncing across multiple machines via Dropbox, iCloud, etc.):
1. **Choose a synced location** for the database:
```bash
# Example: Use a synced folder (Dropbox, iCloud, network drive)
mkdir -p ~/Dropbox/mcp-toolz-shared
```
2. **Update `.env` file** or MCP config to point to the synced database:
```bash
# In .env file
MCP_TOOLZ_DB_PATH=~/Dropbox/mcp-toolz-shared/contexts.db
```
Or in your MCP config:
```json
{
"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. **Restart Claude Code** - it now uses the synced database location
### How It Works
- **Contexts**: Organized by `project_path` (each directory gets its own contexts)
- **Session Tracking**: Contexts tagged with session ID and timestamp for easy restoration
- **Todos**: Organized by `project_path` (each directory gets its own snapshots)
- **Single SQLite DB**: All data stored in one database, filtered by project and session
- **Automatic Updates**: Changes made in one session are immediately visible to others
### Use Cases
- **Multiple machines**: Keep contexts in sync across laptop and desktop
- **Session continuity**: Pick up where you left off after restarting Claude Code
## CLI Usage (Alternative)
```bash
# Get ChatGPT's opinion on something
./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"
# Save your current todos
./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"
# List everything
./mcp-toolz context list
./mcp-toolz todo list
# Restore todos later
./mcp-toolz todo restore
```
## Command Reference
### Context Commands
```bash
# Save and query ChatGPT immediately
./mcp-toolz context save-and-query \
--type <type> \
--title "Title" \
--content "..." \
--tags "tag1,tag2"
# Save without querying
./mcp-toolz context save --type code --file path/to/file.py
# Ask ChatGPT or Claude about existing context
./mcp-toolz context ask-chatgpt <context-id> [--question "Your question"]
./mcp-toolz context ask-claude <context-id> [--question "Your question"]
# Browse and search
./mcp-toolz context list [--limit N] [--type TYPE]
./mcp-toolz context search "query"
./mcp-toolz context show <context-id>
# Delete
./mcp-toolz context delete <context-id>
```
**Context Types:**
- `suggestion` - Architecture decisions, implementation plans
- `code` - Code snippets, implementations
- `conversation` - Discussions, Q&A sessions
- `error` - Error messages, stack traces, debugging
### Todo Commands
```bash
# Save current todos
./mcp-toolz todo save \
--todos '[{"content":"...","status":"pending","activeForm":"..."}]' \
--context "What you're working on"
# Restore (defaults to active snapshot for current project)
./mcp-toolz todo restore [<snapshot-id>]
# Browse and search
./mcp-toolz todo list [--project-path PATH]
./mcp-toolz todo search "query"
./mcp-toolz todo show <snapshot-id>
# Delete
./mcp-toolz todo delete <snapshot-id>
```
**Todo Status:** `pending`, `in_progress`, `completed`
### Get Help
```bash
./mcp-toolz --help
./mcp-toolz context --help
./mcp-toolz todo --help
```
## Common Workflows
### Get Multiple AI Perspectives
When evaluating an implementation, compare insights from different AI models:
```bash
./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"
```
The AI's response appears immediately in your console. You can also ask specific questions or get Claude's perspective:
```bash
# Ask a specific question about the context
./mcp-toolz context ask-chatgpt <context-id> --question "What are the scalability concerns?"
# Get Claude's general opinion
./mcp-toolz context ask-claude <context-id>
# Or ask Claude a specific question
./mcp-toolz context ask-claude <context-id> --question "How would you handle database migrations?"
```
### Debug with Two Perspectives
```bash
./mcp-toolz context save-and-query \
--type error \
--title "CORS issue in production" \
--content "Error: blocked by CORS policy. Headers: ..." \
--tags "debugging,cors,production"
```
### Session Continuity
```bash
# End of work session
./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"
# Next session
./mcp-toolz todo restore
```
### Share Across Claude Code Sessions
```bash
# Session 1: Save interesting discussions
./mcp-toolz context save \
--type conversation \
--title "Performance optimization ideas" \
--content "..." \
--tags "performance"
# Session 2: Find and review
./mcp-toolz context search "performance"
./mcp-toolz context show <context-id>
# Or ask AI specific questions
./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?"
```
## Environment Variables
```bash
# Required (at least one for AI features)
OPENAI_API_KEY=sk-... # Your OpenAI API key
ANTHROPIC_API_KEY=sk-ant-... # Your Anthropic API key
GOOGLE_API_KEY=... # Your Google API key (for Gemini)
DEEPSEEK_API_KEY=sk-... # Your DeepSeek API key
# Optional
MCP_TOOLZ_DB_PATH=~/.mcp-toolz/contexts.db # Shared database location (default)
MCP_TOOLZ_MODEL=gpt-5 # OpenAI model (default: gpt-5)
MCP_TOOLZ_CLAUDE_MODEL=claude-sonnet-4-5-20250929 # Claude model
MCP_TOOLZ_GEMINI_MODEL=gemini-2.0-flash-thinking-exp-01-21 # Gemini model
MCP_TOOLZ_DEEPSEEK_MODEL=deepseek-chat # DeepSeek model
```
## Troubleshooting
### "Error 401: Invalid API key"
- Verify API keys are set in `.env` (OPENAI_API_KEY and/or ANTHROPIC_API_KEY)
- Check billing is enabled on your OpenAI/Anthropic account
- The `./mcp-toolz` wrapper automatically unsets shell environment variables to use `.env`
### "No module named context_manager"
- Use `./mcp-toolz` helper script (recommended)
- Or set `PYTHONPATH=src` before running Python directly
### Commands not found
- Activate venv: `source venv/bin/activate`
- Make script executable: `chmod +x mcp-toolz`
### Todos not restoring
- Check you're in the same project directory
- Use `./mcp-toolz todo list` to see all snapshots
- Restore specific snapshot: `./mcp-toolz todo restore <snapshot-id>`
## Project Structure
```
mcp-toolz/
├── src/
│ ├── mcp_server/ # MCP server for Claude Code
│ │ └── server.py # MCP tools and resources
│ ├── context_manager/ # CLI and storage
│ │ ├── cli.py # Click-based CLI
│ │ ├── storage.py # SQLite operations
│ │ ├── openai_client.py # ChatGPT API client
│ │ └── anthropic_client.py # Claude API client
│ └── models.py # Pydantic data models
├── data/
│ └── contexts.db # SQLite database
├── requirements.txt
├── requirements-dev.txt
└── mcp-toolz # Helper script
```
## Development
### Setup for Contributors
```bash
# Clone and install
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
# Install pre-commit hooks (IMPORTANT!)
pre-commit install
# Copy and configure .env
cp .env.example .env
# Edit .env with your API keys
```
### Running Tests
```bash
source venv/bin/activate
pytest
```
### Code Quality
[](https://github.com/pre-commit/pre-commit)
[](https://github.com/psf/black)
[](https://github.com/astral-sh/ruff)
[](https://mypy-lang.org/)
[](https://pycqa.github.io/isort/)
[](https://github.com/PyCQA/bandit)
```bash
# Run all checks (runs automatically on commit after pre-commit install)
pre-commit run --all-files
# Individual tools
black .
ruff check .
mypy src/
```
## Tips
1. **Use descriptive titles** - Makes searching easier later
2. **Add relevant tags** - Helps organize and find contexts
3. **Be specific in content** - More detail = better AI responses
4. **Compare AI opinions** - Get both ChatGPT and Claude perspectives on important decisions
5. **Review AI suggestions** - They're helpful opinions, not rules
6. **Save todos regularly** - Build habit of saving at end of sessions
## License
MIT
Raw data
{
"_id": null,
"home_page": null,
"name": "mcp-toolz",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.13",
"maintainer_email": null,
"keywords": "mcp, model-context-protocol, claude-code, context-management, todo-persistence, ai-assistant, chatgpt, anthropic, gemini, deepseek",
"author": null,
"author_email": "Taylor Leese <tleese22@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/81/af/e45babbe4d5813d72fc1bc7c581f8af957d88740eda73b468acf9f510e76/mcp_toolz-0.3.7.tar.gz",
"platform": null,
"description": "# MCP Toolz\n\nmcp-name: io.github.taylorleese/mcp-toolz\n\n[](https://github.com/taylorleese/mcp-toolz/actions/workflows/ci.yml)\n[](https://github.com/taylorleese/mcp-toolz/issues)\n[](https://github.com/taylorleese/mcp-toolz/commits/main)\n[](https://codecov.io/gh/taylorleese/mcp-toolz)\n[](https://pypi.org/project/mcp-toolz/)\n[](https://www.python.org/downloads/)\n[](https://modelcontextprotocol.io)\n[](https://opensource.org/licenses/MIT)\n\n[](https://github.com/pre-commit/pre-commit)\n[](https://www.bestpractices.dev/projects/11358)\n[](https://scorecard.dev/viewer/?uri=github.com/taylorleese/mcp-toolz)\n[](https://github.com/taylorleese/mcp-toolz/blob/main/.github/dependabot.yml)\n\nMCP server for Claude Code providing context management, todo persistence, and multi-AI perspectives. Share contexts and todos across sessions, compare insights from ChatGPT, Claude, Gemini, and DeepSeek, and access everything via MCP tools.\n\n## Features\n\n- **\ud83d\udd0c MCP Server**: Works NOW with Claude Code - full tool integration ready\n- **Session Continuity**: Never lose context when restarting Claude Code - restore \"what was I working on last session\"\n- **Project Organization**: Contexts and todos automatically organized by project directory\n- **Session Tracking**: Every Claude Code session gets a unique ID - track your work over time\n- **Multi-AI Perspectives**: Compare feedback from ChatGPT (OpenAI), Claude (Anthropic), Gemini (Google), and DeepSeek on your code and decisions\n- **Context Types**: Save conversations, code snippets, architectural suggestions, or error traces\n- **Persistent Todos**: Save and restore your todo list across sessions - never forget where you left off\n- **Full-Text Search**: Find anything by content, tags, project, or session\n- **CLI + MCP**: Use via Claude Code MCP tools or standalone CLI commands\n\n## Quick Start\n\n### Installation\n\n#### From PyPI (Recommended)\n\n```bash\npip install mcp-toolz\n```\n\n#### From Source (Development)\n\n```bash\n# Clone the repository\ngit clone https://github.com/taylorleese/mcp-toolz.git\ncd mcp-toolz\n\n# Create and activate virtual environment\npython3 -m venv venv\nsource venv/bin/activate # macOS/Linux\n# or: venv\\Scripts\\activate # Windows\n\n# Install in editable mode with dev dependencies\npip install -e \".[dev]\"\n```\n\n### Configuration\n\n```bash\n# Set your API keys as environment variables (at least one required for AI features)\nexport OPENAI_API_KEY=sk-... # For ChatGPT\nexport ANTHROPIC_API_KEY=sk-ant-... # For Claude\nexport GOOGLE_API_KEY=... # For Gemini\nexport DEEPSEEK_API_KEY=sk-... # For DeepSeek\n\n# Or create a .env file (if installing from source)\ncp .env.example .env\n# Edit .env and add your API keys\n```\n\n### MCP Server Setup (Recommended)\n\nThe primary way to use mcp-toolz is via the MCP server in Claude Code:\n\n1. **Add to Claude Code settings** (add this JSON to your Claude Code MCP settings):\n\n**If installed via pip:**\n\n```json\n{\n \"mcpServers\": {\n \"mcp-toolz\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"mcp_server\"],\n \"env\": {\n \"OPENAI_API_KEY\": \"sk-...\",\n \"ANTHROPIC_API_KEY\": \"sk-ant-...\",\n \"GOOGLE_API_KEY\": \"...\",\n \"DEEPSEEK_API_KEY\": \"sk-...\"\n }\n }\n }\n}\n```\n\n**If installed from source:**\n\n```json\n{\n \"mcpServers\": {\n \"mcp-toolz\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"mcp_server\"],\n \"cwd\": \"/absolute/path/to/mcp-toolz\",\n \"env\": {\n \"PYTHONPATH\": \"/absolute/path/to/mcp-toolz/src\"\n }\n }\n }\n}\n```\n\n2. **Configure API keys** - Add your API keys to the `env` section (pip) or `.env` file (source)\n\n3. **Restart Claude Code** to load the MCP server\n\n4. **Use MCP tools in Claude Code**:\n - \"Save this context about authentication\"\n - \"Ask ChatGPT about the last context I saved\"\n - \"Show my active todos\"\n - \"Search contexts tagged with 'bug'\"\n\nAll MCP tools are automatically available - see [MCP Server Tools](#mcp-server-tools) below.\n\n## MCP Server Tools\n\nThe MCP server works NOW with Claude Code and provides these tools:\n\n**Context Tools:**\n\n- `context_save` - Save a new context (automatically includes session info)\n- `context_search` - Search by query or tags\n- `context_get` - Get by ID\n- `context_list` - List recent\n- `context_delete` - Delete by ID\n\n**Multi-AI Perspective Tools:**\n\n- `ask_chatgpt` - Get ChatGPT's analysis of a context (supports custom questions)\n- `ask_claude` - Get Claude's analysis of a context (supports custom questions)\n- `ask_gemini` - Get Gemini's analysis of a context (supports custom questions)\n- `ask_deepseek` - Get DeepSeek's analysis of a context (supports custom questions)\n\n**Todo Tools:**\n\n- `todo_search` - Search snapshots\n- `todo_get` - Get by ID\n- `todo_list` - List recent\n- `todo_save` - Save snapshot\n- `todo_restore` - Get active/specific snapshot\n- `todo_delete` - Delete by ID\n\n**Session Tracking:**\nWhen saving contexts through MCP tools, they are automatically tagged with:\n\n- Current project directory (`project_path`)\n- Session ID (unique per Claude Code session)\n- Session timestamp (when the session started)\n\n**Future:** Once ChatGPT Desktop adds MCP support, you'll be able to use these same tools there too.\n\n## Usage Examples\n\nHere are practical examples of how to use mcp-toolz in Claude Code:\n\n### Example 1: Get Multiple AI Perspectives on Architecture Decisions\n\n**Prompt:**\n\n```\nI'm deciding between using Redis or Memcached for caching user sessions.\nSave this as a context and ask ChatGPT for their analysis.\nUse tags: caching, redis, memcached, architecture\n```\n\n**What happens:**\n\n1. Claude Code uses `context_save` to save your architectural decision\n2. Then uses `ask_chatgpt` to get ChatGPT's perspective\n3. You can compare multiple AI perspectives to inform your decision\n\n**Follow-up prompts:**\n\n- \"Ask Claude the same question for comparison\"\n- \"Ask Gemini for another perspective\"\n- \"What does DeepSeek think about this?\"\n- \"Search my contexts tagged with 'architecture'\"\n\n### Example 2: Session Continuity - Never Lose Your Place\n\n**Prompt (end of work session):**\n\n```\nSave my current todo list so I can restore it tomorrow\n```\n\n**What happens:**\n\n1. Claude Code uses `todo_save` to snapshot your current work state\n2. Todos are saved with project path and timestamp\n\n**Next day prompt:**\n\n```\nWhat was I working on yesterday? Restore my todos.\n```\n\n**What happens:**\n\n1. Claude Code uses `todo_restore` to get your last snapshot\n2. Shows you exactly where you left off\n3. You can jump right back into work\n\n### Example 3: Debug with Multiple AI Perspectives\n\n**Prompt:**\n\n```\nI'm getting \"TypeError: Cannot read property 'map' of undefined\" in my React component.\nThe error occurs in UserList.jsx when rendering the users array.\nSave this as an error context and ask ChatGPT, Claude, and Gemini for debugging suggestions.\nTags: react, debugging, javascript\n```\n\n**What happens:**\n\n1. Claude Code uses `context_save` to record the error\n2. Uses `ask_chatgpt` to get OpenAI's debugging approach\n3. Uses `ask_claude` to get Anthropic's perspective\n4. Uses `ask_gemini` for Google's analysis\n5. You can compare different debugging strategies from multiple AI models\n\n**Follow-up prompts:**\n\n- \"Search for other contexts tagged with 'react' bugs\"\n- \"Show me contexts from my last session\"\n\n### Example 4: Track Performance Optimization Ideas\n\n**Prompt:**\n\n```\nSave this performance optimization idea: \"Lazy load images below the fold using\nIntersection Observer API. Estimated 40% reduction in initial page load.\"\nType: suggestion, Tags: performance, optimization, images\n```\n\n**What happens:**\n\n1. Claude Code uses `context_save` with type \"suggestion\"\n2. Context is searchable and tied to current project\n3. Available across all future sessions\n\n**Later prompt:**\n\n```\nSearch my contexts for performance optimization ideas\n```\n\n**What happens:**\n\n1. Claude Code uses `context_search` with your query\n2. Returns all matching contexts across sessions\n3. You can review past optimization ideas\n\n### Example 5: Cross-Session Knowledge Sharing\n\n**Prompt (in Project A):**\n\n```\nI figured out how to handle OAuth refresh tokens properly.\nSave this so I can reference it in other projects:\n\"Store refresh tokens in httpOnly cookies, access tokens in memory only.\nRotate refresh tokens on each use. Set 7-day expiry on refresh, 15min on access.\"\nType: code, Tags: oauth, security, authentication\n```\n\n**Prompt (later in Project B):**\n\n```\nHow did I implement OAuth refresh tokens in my last project?\nSearch for contexts about oauth and show me what I saved.\n```\n\n**What happens:**\n\n1. Claude Code uses `context_search` to find your OAuth implementation\n2. Retrieves the context across projects\n3. You reuse your own knowledge without starting from scratch\n\n## Sharing Contexts Between Agents\n\nmcp-toolz makes it easy to share contexts and todos across multiple Claude Code sessions or agents.\n\n### MCP Resources (Passive Discovery)\n\nClaude Code can automatically discover and read contexts/todos via MCP resources:\n\n**Context Resources:**\n\n- `mcp-toolz://contexts/project/recent` - Recent contexts for current project\n- `mcp-toolz://contexts/project/sessions` - List of recent Claude Code sessions for current project\n- `mcp-toolz://contexts/session/{session_id}` - All contexts from a specific session\n\n**Todo Resources:**\n\n- `mcp-toolz://todos/recent` - Last 20 todo snapshots (all projects)\n- `mcp-toolz://todos/active` - Active todos for current working directory\n\n**Session Tracking:**\nEach Claude Code session automatically gets a unique session ID. All contexts saved during that session are tagged with:\n\n- `session_id` - UUID of the Claude Code session\n- `session_timestamp` - When the session started\n- `project_path` - Directory where the context was created\n\nThis makes it easy to restore context from previous sessions: \"Show me what I was working on in my last session\"\n\nResources are read-only views into the shared database. Claude Code can discover them automatically without explicit tool calls.\n\n### Shared Database Setup\n\n**By default**, mcp-toolz stores all data in `~/.mcp-toolz/contexts.db`, which is automatically shared across all projects on the same machine. No additional configuration needed!\n\n**For advanced use cases** (syncing across multiple machines via Dropbox, iCloud, etc.):\n\n1. **Choose a synced location** for the database:\n\n```bash\n# Example: Use a synced folder (Dropbox, iCloud, network drive)\nmkdir -p ~/Dropbox/mcp-toolz-shared\n```\n\n2. **Update `.env` file** or MCP config to point to the synced database:\n\n```bash\n# In .env file\nMCP_TOOLZ_DB_PATH=~/Dropbox/mcp-toolz-shared/contexts.db\n```\n\nOr in your MCP config:\n\n```json\n{\n \"mcpServers\": {\n \"mcp-toolz\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"mcp_server\"],\n \"cwd\": \"/absolute/path/to/mcp-toolz\",\n \"env\": {\n \"PYTHONPATH\": \"/absolute/path/to/mcp-toolz/src\",\n \"MCP_TOOLZ_DB_PATH\": \"/Users/you/Dropbox/mcp-toolz-shared/contexts.db\"\n }\n }\n }\n}\n```\n\n3. **Restart Claude Code** - it now uses the synced database location\n\n### How It Works\n\n- **Contexts**: Organized by `project_path` (each directory gets its own contexts)\n- **Session Tracking**: Contexts tagged with session ID and timestamp for easy restoration\n- **Todos**: Organized by `project_path` (each directory gets its own snapshots)\n- **Single SQLite DB**: All data stored in one database, filtered by project and session\n- **Automatic Updates**: Changes made in one session are immediately visible to others\n\n### Use Cases\n\n- **Multiple machines**: Keep contexts in sync across laptop and desktop\n- **Session continuity**: Pick up where you left off after restarting Claude Code\n\n## CLI Usage (Alternative)\n\n```bash\n# Get ChatGPT's opinion on something\n./mcp-toolz context save-and-query \\\n --type suggestion \\\n --title \"Redis caching strategy\" \\\n --content \"Use Redis for session storage with 1-hour TTL\" \\\n --tags \"caching,redis\"\n\n# Save your current todos\n./mcp-toolz todo save \\\n --todos '[\n {\"content\":\"Fix auth bug\",\"status\":\"in_progress\",\"activeForm\":\"Fixing auth bug\"},\n {\"content\":\"Write tests\",\"status\":\"pending\",\"activeForm\":\"Writing tests\"}\n ]' \\\n --context \"Working on authentication\"\n\n# List everything\n./mcp-toolz context list\n./mcp-toolz todo list\n\n# Restore todos later\n./mcp-toolz todo restore\n```\n\n## Command Reference\n\n### Context Commands\n\n```bash\n# Save and query ChatGPT immediately\n./mcp-toolz context save-and-query \\\n --type <type> \\\n --title \"Title\" \\\n --content \"...\" \\\n --tags \"tag1,tag2\"\n\n# Save without querying\n./mcp-toolz context save --type code --file path/to/file.py\n\n# Ask ChatGPT or Claude about existing context\n./mcp-toolz context ask-chatgpt <context-id> [--question \"Your question\"]\n./mcp-toolz context ask-claude <context-id> [--question \"Your question\"]\n\n# Browse and search\n./mcp-toolz context list [--limit N] [--type TYPE]\n./mcp-toolz context search \"query\"\n./mcp-toolz context show <context-id>\n\n# Delete\n./mcp-toolz context delete <context-id>\n```\n\n**Context Types:**\n\n- `suggestion` - Architecture decisions, implementation plans\n- `code` - Code snippets, implementations\n- `conversation` - Discussions, Q&A sessions\n- `error` - Error messages, stack traces, debugging\n\n### Todo Commands\n\n```bash\n# Save current todos\n./mcp-toolz todo save \\\n --todos '[{\"content\":\"...\",\"status\":\"pending\",\"activeForm\":\"...\"}]' \\\n --context \"What you're working on\"\n\n# Restore (defaults to active snapshot for current project)\n./mcp-toolz todo restore [<snapshot-id>]\n\n# Browse and search\n./mcp-toolz todo list [--project-path PATH]\n./mcp-toolz todo search \"query\"\n./mcp-toolz todo show <snapshot-id>\n\n# Delete\n./mcp-toolz todo delete <snapshot-id>\n```\n\n**Todo Status:** `pending`, `in_progress`, `completed`\n\n### Get Help\n\n```bash\n./mcp-toolz --help\n./mcp-toolz context --help\n./mcp-toolz todo --help\n```\n\n## Common Workflows\n\n### Get Multiple AI Perspectives\n\nWhen evaluating an implementation, compare insights from different AI models:\n\n```bash\n./mcp-toolz context save-and-query \\\n --type suggestion \\\n --title \"Microservices vs Monolith for e-commerce\" \\\n --content \"Building platform with 5 services. Start microservices or monolith first?\" \\\n --tags \"architecture,scalability\"\n```\n\nThe AI's response appears immediately in your console. You can also ask specific questions or get Claude's perspective:\n\n```bash\n# Ask a specific question about the context\n./mcp-toolz context ask-chatgpt <context-id> --question \"What are the scalability concerns?\"\n\n# Get Claude's general opinion\n./mcp-toolz context ask-claude <context-id>\n\n# Or ask Claude a specific question\n./mcp-toolz context ask-claude <context-id> --question \"How would you handle database migrations?\"\n```\n\n### Debug with Two Perspectives\n\n```bash\n./mcp-toolz context save-and-query \\\n --type error \\\n --title \"CORS issue in production\" \\\n --content \"Error: blocked by CORS policy. Headers: ...\" \\\n --tags \"debugging,cors,production\"\n```\n\n### Session Continuity\n\n```bash\n# End of work session\n./mcp-toolz todo save \\\n --todos '[\n {\"content\":\"Implement login\",\"status\":\"completed\",\"activeForm\":\"Implementing login\"},\n {\"content\":\"Add OAuth\",\"status\":\"in_progress\",\"activeForm\":\"Adding OAuth\"},\n {\"content\":\"Write tests\",\"status\":\"pending\",\"activeForm\":\"Writing tests\"}\n ]' \\\n --context \"Day 2 of auth feature\"\n\n# Next session\n./mcp-toolz todo restore\n```\n\n### Share Across Claude Code Sessions\n\n```bash\n# Session 1: Save interesting discussions\n./mcp-toolz context save \\\n --type conversation \\\n --title \"Performance optimization ideas\" \\\n --content \"...\" \\\n --tags \"performance\"\n\n# Session 2: Find and review\n./mcp-toolz context search \"performance\"\n./mcp-toolz context show <context-id>\n\n# Or ask AI specific questions\n./mcp-toolz context ask-chatgpt <context-id> --question \"What's the performance impact?\"\n./mcp-toolz context ask-claude <context-id> --question \"Are there any security concerns?\"\n```\n\n## Environment Variables\n\n```bash\n# Required (at least one for AI features)\nOPENAI_API_KEY=sk-... # Your OpenAI API key\nANTHROPIC_API_KEY=sk-ant-... # Your Anthropic API key\nGOOGLE_API_KEY=... # Your Google API key (for Gemini)\nDEEPSEEK_API_KEY=sk-... # Your DeepSeek API key\n\n# Optional\nMCP_TOOLZ_DB_PATH=~/.mcp-toolz/contexts.db # Shared database location (default)\nMCP_TOOLZ_MODEL=gpt-5 # OpenAI model (default: gpt-5)\nMCP_TOOLZ_CLAUDE_MODEL=claude-sonnet-4-5-20250929 # Claude model\nMCP_TOOLZ_GEMINI_MODEL=gemini-2.0-flash-thinking-exp-01-21 # Gemini model\nMCP_TOOLZ_DEEPSEEK_MODEL=deepseek-chat # DeepSeek model\n```\n\n## Troubleshooting\n\n### \"Error 401: Invalid API key\"\n\n- Verify API keys are set in `.env` (OPENAI_API_KEY and/or ANTHROPIC_API_KEY)\n- Check billing is enabled on your OpenAI/Anthropic account\n- The `./mcp-toolz` wrapper automatically unsets shell environment variables to use `.env`\n\n### \"No module named context_manager\"\n\n- Use `./mcp-toolz` helper script (recommended)\n- Or set `PYTHONPATH=src` before running Python directly\n\n### Commands not found\n\n- Activate venv: `source venv/bin/activate`\n- Make script executable: `chmod +x mcp-toolz`\n\n### Todos not restoring\n\n- Check you're in the same project directory\n- Use `./mcp-toolz todo list` to see all snapshots\n- Restore specific snapshot: `./mcp-toolz todo restore <snapshot-id>`\n\n## Project Structure\n\n```\nmcp-toolz/\n\u251c\u2500\u2500 src/\n\u2502 \u251c\u2500\u2500 mcp_server/ # MCP server for Claude Code\n\u2502 \u2502 \u2514\u2500\u2500 server.py # MCP tools and resources\n\u2502 \u251c\u2500\u2500 context_manager/ # CLI and storage\n\u2502 \u2502 \u251c\u2500\u2500 cli.py # Click-based CLI\n\u2502 \u2502 \u251c\u2500\u2500 storage.py # SQLite operations\n\u2502 \u2502 \u251c\u2500\u2500 openai_client.py # ChatGPT API client\n\u2502 \u2502 \u2514\u2500\u2500 anthropic_client.py # Claude API client\n\u2502 \u2514\u2500\u2500 models.py # Pydantic data models\n\u251c\u2500\u2500 data/\n\u2502 \u2514\u2500\u2500 contexts.db # SQLite database\n\u251c\u2500\u2500 requirements.txt\n\u251c\u2500\u2500 requirements-dev.txt\n\u2514\u2500\u2500 mcp-toolz # Helper script\n```\n\n## Development\n\n### Setup for Contributors\n\n```bash\n# Clone and install\ngit clone https://github.com/taylorleese/mcp-toolz.git\ncd mcp-toolz\npython3 -m venv venv\nsource venv/bin/activate\npip install -r requirements-dev.txt\n\n# Install pre-commit hooks (IMPORTANT!)\npre-commit install\n\n# Copy and configure .env\ncp .env.example .env\n# Edit .env with your API keys\n```\n\n### Running Tests\n\n```bash\nsource venv/bin/activate\npytest\n```\n\n### Code Quality\n\n[](https://github.com/pre-commit/pre-commit)\n[](https://github.com/psf/black)\n[](https://github.com/astral-sh/ruff)\n[](https://mypy-lang.org/)\n[](https://pycqa.github.io/isort/)\n[](https://github.com/PyCQA/bandit)\n\n```bash\n# Run all checks (runs automatically on commit after pre-commit install)\npre-commit run --all-files\n\n# Individual tools\nblack .\nruff check .\nmypy src/\n```\n\n## Tips\n\n1. **Use descriptive titles** - Makes searching easier later\n2. **Add relevant tags** - Helps organize and find contexts\n3. **Be specific in content** - More detail = better AI responses\n4. **Compare AI opinions** - Get both ChatGPT and Claude perspectives on important decisions\n5. **Review AI suggestions** - They're helpful opinions, not rules\n6. **Save todos regularly** - Build habit of saving at end of sessions\n\n## License\n\nMIT\n",
"bugtrack_url": null,
"license": null,
"summary": "Save contexts and todos across Claude Code sessions, get feedback from ChatGPT, Claude, Gemini, and DeepSeek",
"version": "0.3.7",
"project_urls": {
"Documentation": "https://github.com/taylorleese/mcp-toolz#readme",
"Homepage": "https://github.com/taylorleese/mcp-toolz",
"Issues": "https://github.com/taylorleese/mcp-toolz/issues",
"Repository": "https://github.com/taylorleese/mcp-toolz"
},
"split_keywords": [
"mcp",
" model-context-protocol",
" claude-code",
" context-management",
" todo-persistence",
" ai-assistant",
" chatgpt",
" anthropic",
" gemini",
" deepseek"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c6cb9e920f79d9668ef955ac1ce21a98d3503f2a511ec7c0c54daa10bea454e3",
"md5": "3b2f624300a3e1d3dfeaffa6171a802b",
"sha256": "a69c4d34d6e94d50d54b248b80f8ddce2754ae6e7f43a022dc29285feb4ba6d0"
},
"downloads": -1,
"filename": "mcp_toolz-0.3.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3b2f624300a3e1d3dfeaffa6171a802b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.13",
"size": 31398,
"upload_time": "2025-10-25T22:41:46",
"upload_time_iso_8601": "2025-10-25T22:41:46.415088Z",
"url": "https://files.pythonhosted.org/packages/c6/cb/9e920f79d9668ef955ac1ce21a98d3503f2a511ec7c0c54daa10bea454e3/mcp_toolz-0.3.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "81afe45babbe4d5813d72fc1bc7c581f8af957d88740eda73b468acf9f510e76",
"md5": "20a1239ba6a4f26ba52c58a2aa8936c3",
"sha256": "06b0d843b82405f65ce4e57437714987994e11aa5909d9bc4ec09972a4b94e30"
},
"downloads": -1,
"filename": "mcp_toolz-0.3.7.tar.gz",
"has_sig": false,
"md5_digest": "20a1239ba6a4f26ba52c58a2aa8936c3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.13",
"size": 43556,
"upload_time": "2025-10-25T22:41:47",
"upload_time_iso_8601": "2025-10-25T22:41:47.679156Z",
"url": "https://files.pythonhosted.org/packages/81/af/e45babbe4d5813d72fc1bc7c581f8af957d88740eda73b468acf9f510e76/mcp_toolz-0.3.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-25 22:41:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "taylorleese",
"github_project": "mcp-toolz#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "mcp",
"specs": [
[
"==",
"1.19.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
"==",
"2.12.3"
]
]
},
{
"name": "openai",
"specs": [
[
"==",
"2.6.1"
]
]
},
{
"name": "anthropic",
"specs": [
[
"==",
"0.71.0"
]
]
},
{
"name": "google-generativeai",
"specs": [
[
"==",
"0.8.5"
]
]
},
{
"name": "click",
"specs": [
[
"==",
"8.3.0"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
"==",
"1.1.1"
]
]
},
{
"name": "aiosqlite",
"specs": [
[
"==",
"0.21.0"
]
]
}
],
"lcname": "mcp-toolz"
}
JSON
