karabas1543/todoist-mcp-web

Web-Accessible Todoist MCP Server

🌐 The first web-accessible Todoist MCP server - Use Todoist directly in Claude Web without any local installation!

Based on community Todoist MCP servers, modified for HTTP web access instead of desktop-only stdio transport.

✨ What Makes This Special

Unlike all other Todoist MCP servers that require local installation and Claude Desktop, this server:

• 🌐 Web-Accessible: Works directly in Claude Web browser interface
• 🚀 Zero Local Setup: Just add the URL - no npm, no config files
• 🔒 Production Ready: HTTPS with secure API key authentication
• 📱 Universal: Works on any device with internet access
• ☁️ Always Online: Cloud-hosted, no local machine required

🆚 Comparison

🚀 Quick Start

Using with Claude Web

1. Get your Todoist API token:

   • Go to Todoist Settings > Integrations > Developer
   • Copy your API token

2. Deploy your own instance (see deployment section below)

3. Add to Claude:

   • Go to Claude Settings → Connectors
   • Click "Add Custom Connector"
   • Enter URL: https://your-domain.com/YOUR_API_KEY/todoist
   • Replace YOUR_API_KEY with a secure key you generate
   • Name it "Todoist Tasks" or similar

4. Start using: Ask Claude to manage your tasks!

🛠️ Available MCP Tools

The server includes comprehensive Todoist integration tools:

• Task Management: Create, update, complete, search, and list tasks
• Project Management: Create, update, and list projects
• Section Management: Create sections and search within projects
• Comments: Add comments to tasks and projects
• Quick Add: Natural language task creation
• Bulk Operations: Handle multiple tasks at once
• Overview: Get complete workspace summaries

🏗️ Deploy Your Own

Prerequisites

• VPS or cloud server with Docker
• Domain name (or use free subdomain - see below)
• Todoist API token

Domain Options

Option A: Own Domain

• Purchase domain from registrars like Namecheap, Porkbun (~$10/year)
• Point A record to your server IP
• Use Let's Encrypt for free SSL

Option B: Free Subdomain Services

• DuckDNS - 5 free subdomains, no expiry
• FreeDNS - 5 free subdomains from shared domains
• No-IP - 3 free subdomains (requires monthly confirmation)

Quick Deployment

1. Clone the repository:

git clone https://github.com/karabas1543/todoist-mcp-web.git
cd todoist-mcp-web

2. Set up environment:

cp .env.example .env
nano .env

Configure your .env:

# Your Todoist API token
TODOIST_API_KEY=your_todoist_api_token_here

# Generate secure API key (see step 3)
MCP_API_KEY=your_secure_random_key_here

3. Generate secure API key:

# Option 1: OpenSSL
openssl rand -base64 24 | tr -d "=+/" | cut -c1-32

# Option 2: Using /dev/urandom
cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1

4. Start services:

docker-compose up -d

5. Configure reverse proxy (nginx example):

For own domain with Certbot SSL:

server {
    listen 443 ssl;
    server_name mcp.yourdomain.com;
    
    ssl_certificate /etc/letsencrypt/live/mcp.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mcp.yourdomain.com/privkey.pem;
    
    location / {
        proxy_pass http://localhost:8902;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # For Server-Sent Events (SSE)
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 86400;
    }
}

For DuckDNS subdomain:

# Get SSL cert for DuckDNS subdomain
sudo certbot certonly --standalone -d yourname.duckdns.org

6. Test your server:

curl https://mcp.yourdomain.com/YOUR_API_KEY/todoist
# Should return: {"name":"todoist-mcp-server","version":"0.1.0",...}

📦 Architecture

Internet → nginx/443 → Caddy/8902 → MCP Server/8901 → Todoist API
              ↓              ↓              ↓
           SSL/TLS    API Key Check   JSON-RPC Protocol

Components

• MCP Server: Node.js TypeScript implementation (based on community servers)
• Caddy: Validates API keys and routes requests
• nginx: SSL termination and public endpoint
• Docker: Containerized deployment for consistency

🔒 Security

• API keys stored in environment variables (never committed)
• .gitignore prevents accidental exposure
• HTTPS only in production
• Request validation at multiple layers
• Rate limiting via Todoist API

🤝 Contributing

This fills a gap in the MCP ecosystem - web-accessible servers for Claude Web users. Contributions welcome!

Areas for Contribution

• 🐛 Bug fixes and error handling improvements
• 📚 Documentation and deployment guides
• 🔧 Additional Todoist features
• 🧪 Tests for reliability
• 🌍 Support for more task management platforms

Development

# Clone and setup
git clone https://github.com/karabas1543/todoist-mcp-web.git
cd todoist-mcp-web
cp .env.example .env

# Development with hot reload
docker-compose -f docker-compose.dev.yml up

# View logs
docker-compose logs -f todoist-mcp

# Run tests (if available)
npm test

📖 Technical Details

MCP Protocol

• Version: 2024-11-05
• Transport: HTTP with Server-Sent Events (SSE)
• Authentication: Path-based API key

Technologies

• Runtime: Node.js 20 LTS
• Language: TypeScript
• Container: Docker with multi-stage builds
• Proxy: Caddy 2.8 with exec plugin

Todoist Integration

• API: Todoist REST API v2
• Rate Limits: Respects Todoist's rate limits
• Features: Full task, project, section, and comment management

🔗 Resources

• MCP Protocol Documentation
• Todoist API Documentation
• Source Code
• Report Issues

📄 License

MIT License - Feel free to use this as a template for other web-accessible MCP servers!

🙏 Credits

Based on community Todoist MCP servers, modified to enable web access. Original implementations use stdio transport for desktop-only usage.

⭐ If this helps you use Todoist with Claude Web, please star the repo!

💡 This project demonstrates how to convert any desktop MCP server to web-accessible format.