Todoist MCP Server

# Todoist MCP Server - Installation Instructions ## Step 1: Save the Files Create a project directory and save all files: ```bash # Create project directory mkdir todoist-mcp-server cd todoist-mcp-server # Save all 5 files in this directory: # - Dockerfile # - requirements.txt # - todoist_server.py # - readme.txt # - CLAUDE.md ``` ## Step 2: Build Docker Image ```bash docker build -t todoist-mcp-server . ``` Expected output: ``` [+] Building X.Xs (X/X) FINISHED => [internal] load build definition from Dockerfile => => transferring dockerfile: XXB => [internal] load .dockerignore ... => exporting to image => => exporting layers => => writing image sha256:... => => naming to docker.io/library/todoist-mcp-server:latest ``` ## Step 3: Get Your Todoist API Token 1. Go to: https://app.todoist.com/app/settings/integrations/developer 2. Scroll down to find the "API token" section 3. Copy your 40-character hexadecimal API token 4. Keep it secure - it provides full access to your Todoist account! Example token format: `a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0` ## Step 4: Set Up Secret Store your Todoist API token securely in Docker: ```bash # Store your token (replace with your actual token) docker mcp secret set TODOIST_API_TOKEN="your-40-character-token-here" # Verify the secret was created successfully docker mcp secret list ``` Expected output: ``` NAME CREATED TODOIST_API_TOKEN XX seconds ago ``` ## Step 5: Create Custom Catalog Create the catalog directory and configuration file: ```bash # Create catalogs directory if it doesn't exist mkdir -p ~/.docker/mcp/catalogs # Copy the custom.yaml file to the catalogs directory cp custom.yaml ~/.docker/mcp/catalogs/custom.yaml ``` Or create it manually: ```bash # Create or edit custom.yaml nano ~/.docker/mcp/catalogs/custom.yaml ``` Then paste the contents from the custom.yaml file provided. ## Step 6: Configure Claude Desktop Edit your Claude Desktop configuration file. ### Configuration File Location: - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - **Linux**: `~/.config/Claude/claude_desktop_config.json` ### Edit the Configuration: ```bash # For macOS/Linux nano ~/Library/Application\ Support/Claude/claude_desktop_config.json # For Windows (in Command Prompt) notepad %APPDATA%\Claude\claude_desktop_config.json ``` ### Add This Configuration: ```json { "mcpServers": { "custom": { "type": "catalog", "path": "[YOUR_HOME]/.docker/mcp/catalogs/custom.yaml" } } } ``` ### Replace [YOUR_HOME] with: - **macOS**: `/Users/your_username` Example: `/Users/john/.docker/mcp/catalogs/custom.yaml` - **Windows**: `C:\\Users\\your_username` (use double backslashes!) Example: `C:\\Users\\john\\.docker\\mcp\\catalogs\\custom.yaml` - **Linux**: `/home/your_username` Example: `/home/john/.docker/mcp/catalogs/custom.yaml` ### Complete macOS Example: ```json { "mcpServers": { "custom": { "type": "catalog", "path": "/Users/john/.docker/mcp/catalogs/custom.yaml" } } } ``` ### Complete Windows Example: ```json { "mcpServers": { "custom": { "type": "catalog", "path": "C:\\Users\\john\\.docker\\mcp\\catalogs\\custom.yaml" } } } ``` ## Step 7: Restart Claude Desktop 1. **Quit Claude Desktop completely** - macOS: Claude → Quit Claude (or Cmd+Q) - Windows: Right-click system tray icon → Exit - Linux: File → Quit 2. **Wait a few seconds** 3. **Start Claude Desktop again** 4. **Your Todoist tools should now appear!** ## Step 8: Test Your Server ### Verify Installation: ```bash # Check if server appears in the list docker mcp server list # Check if the container is running docker ps | grep todoist # View logs if needed docker logs $(docker ps | grep todoist | awk '{print $1}') ``` ### Test in Claude Desktop: Try these example commands: 1. **"Create a task 'Test MCP integration' due tomorrow"** 2. **"List all my tasks"** 3. **"Create a project called 'MCP Testing'"** 4. **"Show me all my projects"** --- ## Troubleshooting ### Issue: Tools Not Appearing in Claude **Checklist:** 1. ✓ Docker image built successfully? ```bash docker images | grep todoist-mcp-server ``` 2. ✓ Catalog file in correct location? ```bash ls -la ~/.docker/mcp/catalogs/custom.yaml ``` 3. ✓ Claude Desktop config correct? ```bash cat ~/Library/Application\ Support/Claude/claude_desktop_config.json ``` 4. ✓ Claude Desktop fully restarted? - Must quit completely and reopen 5. ✓ Check Claude Desktop logs (if available) ### Issue: Authentication Errors **Solution:** 1. Verify secret exists: ```bash docker mcp secret list ``` 2. Ensure secret name is exactly `TODOIST_API_TOKEN` 3. Test your token manually: ```bash curl -X GET \ https://api.todoist.com/rest/v2/projects \ -H "Authorization: Bearer YOUR_TOKEN_HERE" ``` 4. If token is invalid, get a new one from Todoist settings ### Issue: API Rate Limiting **Symptoms:** - Getting HTTP 429 errors - "Too many requests" messages **Solution:** - Todoist limits: 1000 requests per 15 minutes per user - Wait 15 minutes before retrying - Batch multiple operations when possible ### Issue: Container Not Starting **Debug steps:** 1. Check container logs: ```bash docker logs $(docker ps -a | grep todoist | awk '{print $1}') ``` 2. Verify environment: ```bash docker mcp server inspect todoist ``` 3. Rebuild without cache: ```bash docker build -t todoist-mcp-server --no-cache . ``` 4. Test locally without Docker: ```bash export TODOIST_API_TOKEN="your-token" python todoist_server.py ``` ### Issue: "Permission Denied" Errors **Solution:** - Ensure Docker Desktop is running - Check Docker permissions - On Linux, you may need: `sudo usermod -aG docker $USER` - Restart terminal after adding to docker group ### Issue: Can't Find Claude Desktop Config **macOS:** ```bash # Create directory if it doesn't exist mkdir -p ~/Library/Application\ Support/Claude # Create config file touch ~/Library/Application\ Support/Claude/claude_desktop_config.json ``` **Windows:** ```cmd # Create directory if it doesn't exist mkdir %APPDATA%\Claude # Create config file type nul > %APPDATA%\Claude\claude_desktop_config.json ``` --- ## Next Steps Once your server is running successfully: 1. **Explore all 16 tools** - Try creating tasks, projects, comments, and labels 2. **Use natural language** - Claude understands context and can help you manage Todoist 3. **Combine operations** - "Create a project and add 3 tasks to it" 4. **Check the readme.txt** - For more usage examples and tips --- ## Need Help? If you encounter issues: 1. Check the logs: `docker logs [container_name]` 2. Verify your API token is valid at https://developer.todoist.com/rest/v2/ 3. Ensure Docker Desktop is running and MCP toolkit is enabled 4. Review the CLAUDE.md file for implementation details --- **Your Todoist MCP server is now ready to use! 🎉** You can manage all your Todoist tasks, projects, comments, and labels through natural language commands in Claude Desktop.