todoist-blade-mcp

A high-performance Model Context Protocol server for Todoist. Dual API strategy (REST v2 + Sync v9), token-efficient output, and a write-gated safety model.

Why this over the official Todoist MCP?

The key differentiator is the Sync v9 integration. No other Todoist MCP server uses it. This unlocks batch commands (bulk-create 50 tasks in one call), incremental sync (delta tokens eliminate redundant fetches), and access to endpoints REST v2 simply doesn't expose.

Features

• 30 tools across 7 categories — projects, sections, tasks, comments, labels, sync, productivity
• Dual API client — REST v2 for simple CRUD, Sync v9 for batch operations and incremental sync
• Token-efficient formatters — pipe-delimited output with null omission, not verbose JSON
• Write-gated safety — all mutations disabled by default; enable with TODOIST_WRITE=true
• Destructive confirmation — delete operations require explicit confirm=true parameter
• Filter query support — full Todoist filter syntax in tasks_list and tasks_search
• Natural language quick-add — dates, priorities, labels, and projects parsed from plain text
• HTTP transport with auth — Bearer token middleware for remote deployments

Quick Start

# Clone
git clone https://github.com/groupthink-dev/todoist-blade-mcp.git
cd todoist-blade-mcp

# Install
pip install -e .

# Run (read-only by default)
export TODOIST_API_TOKEN="your-api-token"
todoist-blade-mcp

To enable write operations:

export TODOIST_WRITE=true

Tools

Projects (6)

Sections (4)

Tasks (9)

Comments (4)

Labels (3)

Sync (2)

Productivity (2)

Filter Query Examples

tasks_list and tasks_search accept Todoist filter syntax:

today                          # Due today
overdue | today                # Overdue or due today
#Work & due before: tomorrow   # Work project, due before tomorrow
p1 & no date                   # Priority 1 with no due date
@waiting & !subtask            # Label "waiting", exclude subtasks
assigned to: me & due: week    # Assigned to me, due this week
created before: -30 days       # Created in the last 30 days

Security Model

Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "todoist": {
      "command": "todoist-blade-mcp",
      "env": {
        "TODOIST_API_TOKEN": "your-api-token",
        "TODOIST_WRITE": "true"
      }
    }
  }
}

Claude Code

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "todoist": {
      "command": "todoist-blade-mcp",
      "env": {
        "TODOIST_API_TOKEN": "your-api-token",
        "TODOIST_WRITE": "true"
      }
    }
  }
}

Environment Variables

Architecture

src/todoist_blade_mcp/
├── server.py       — FastMCP server, 30 @mcp.tool decorators
├── client.py       — Dual API client (REST v2 + Sync v9), delta tokens
├── formatters.py   — Token-efficient output (pipe-delimited, null omission)
├── models.py       — Config, write-gate, batch limits
└── auth.py         — Bearer token middleware for HTTP transport

REST v2 handles individual CRUD — get a task, create a project, post a comment. Straightforward request/response.

Sync v9 handles everything REST can't. Incremental sync uses a sync_token (delta token) so subsequent calls only return what changed. Batch mode packs up to 100 heterogeneous commands (create tasks, move sections, complete items) into a single API call and returns per-command results.

Formatters convert API responses to pipe-delimited text with null fields omitted. A task that would be 800 tokens as formatted JSON becomes ~300 tokens. Over a multi-turn conversation this compounds significantly.

Development

# Install in development mode
make install-dev

# Run tests
make test

# Lint
make lint

# Type check
make typecheck

# Format
make fmt

License

MIT