NeiSnR/todoist-remote-mcp-server

Todoist Remote MCP Server

Manage your Todoist tasks directly through Claude AI conversations

Deploy once and connect Claude to your Todoist account. Use our ready-made Docker image - no technical knowledge required.

🚀 Quick Start (2 minutes)

The easiest way - just one command:

# 1. Get your Todoist API token from: https://todoist.com/app/settings/integrations
# 2. Run this command (replace YOUR_TOKEN):

docker run -d \
  --name todoist-mcp \
  -p 8080:8080 \
  -e TODOIST_API_TOKEN=YOUR_TOKEN \
  -e PUBLIC_URL=http://your-server-ip:8080 \
  --restart unless-stopped \
  neisn/todoist-remote-mcp-server:latest

That's it! Your server is running at http://your-server-ip:8080

Skip to connecting Claude →

📋 Other Deployment Options

🐳 Method 1: Docker Compose (Recommended for VPS)

Best for: Users with a VPS who want easy management

# 1. Create docker-compose.yml
cat > docker-compose.yml << 'EOF'
version: '3.8'
services:
  todoist-mcp:
    image: neisn/todoist-remote-mcp-server:latest
    container_name: todoist-remote-mcp-server
    ports:
      - "8080:8080"
    environment:
      - TODOIST_API_TOKEN=YOUR_TOKEN_HERE
      - PUBLIC_URL=https://your-domain.com
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
EOF

# 2. Start the server
docker-compose up -d

☁️ Method 2: Cloud Platforms (No Server Needed)

Best for: Beginners who don't want to manage servers

Option A: Railway (Recommended)

1. Go to Railway.app and sign up
2. Click "New Project" → "Deploy from GitHub repo"
3. Connect this repository: https://github.com/NeiSnR/todoist-remote-mcp-server
4. Add environment variable: TODOIST_API_TOKEN = your token
5. Copy your Railway URL and connect to Claude

Option B: DigitalOcean App Platform

1. Sign up at DigitalOcean.com
2. Go to "App Platform" → "Create App"
3. Connect this repository: https://github.com/NeiSnR/todoist-remote-mcp-server
4. Add environment variable: TODOIST_API_TOKEN = your token
5. Copy your app URL and connect to Claude

⚙️ Method 3: Advanced Setup (For Power Users)

Need reverse proxy, SSL, or custom setup?

Check our complete examples in :

• Nginx Reverse Proxy (with SSL)
• Traefik (advanced users)
• Caddy (automatic SSL)

For development: Use

🔗 Connect to Claude AI

After deploying with any method above:

1. Get your server URL:

   • Quick Start: http://your-server-ip:8080
   • Cloud platforms: Copy the URL they provide
   • Your domain: https://yourdomain.com

2. Connect to Claude:

   • Go to Claude.ai
   • Look for "Custom Connectors" or "Integrations"
   • Add new connector with your server URL
   • Complete the authorization (click "Allow")

3. Start using:

   "Show me my Todoist tasks for today"
   "Create a task: Call dentist tomorrow at 2pm"
   "What projects do I have?"
   "Mark task 'grocery shopping' as complete"
   

⚙️ Configuration

Required Setup

Get your Todoist API Token:

• Go to Todoist Settings → Integrations
• Copy the "API token"
• Use it in your deployment method

Environment Variables

# Required
TODOIST_API_TOKEN=your_token_from_todoist

# Optional (auto-detected in most cases)
PUBLIC_URL=https://your-domain.com
PORT=8080

🛠️ What You Can Do

Once connected, manage your entire Todoist through Claude:

• ✅ Tasks: Create, update, complete, delete
• 📁 Projects: Create and organize projects
• 🏷️ Labels: Add and manage labels
• 💬 Comments: Add comments to tasks
• 🔍 Search: Find tasks with filters
• 📊 Reports: Get task summaries

Example commands:

"Create a new project called 'Home Renovation'"
"Add task 'Buy paint' to Home Renovation project with high priority"
"Show me all overdue tasks"
"What are my tasks for this week?"

🆘 Need Help?

Common Issues

"Can't connect to server"

• Make sure your server is running: docker ps
• Check your URL is correct (include http:// or https://)
• Wait 2-3 minutes after first deployment

"Invalid token"

• Get a new token from Todoist Settings
• Make sure you copied the full token (no spaces)
• Restart your container after changing the token

"OAuth authorization failed"

• Your PUBLIC_URL must match your actual server URL
• Make sure your server is accessible from the internet

Get Support

• Issues: GitHub Issues
• Examples:
  • docker-compose.example.yml - Production options (Nginx, Traefik, Caddy)
  • docker-compose.local.yml - Local development

📄 License

MIT License - Free to use and modify

🙏 Acknowledgments

• Todoist - For the excellent task management API
• Claude AI - For Custom Connectors feature
• Anthropic - For the Model Context Protocol (MCP)
• MCP Documentation - For the protocol specification

Made for productivity enthusiasts who want AI-powered task management ⚡