todoist-mcp-server

jimdaga/todoist-mcp-server

3.1

If you are the rightful owner of todoist-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Todoist MCP Server integrates Todoist with AI assistants like Claude, allowing users to manage tasks, projects, and labels through conversational AI.

Tools
7
Resources
0
Prompts
0

Todoist MCP Server

A Model Context Protocol (MCP) server that integrates Todoist with Claude and other AI assistants. Manage your tasks, projects, and labels directly through conversational AI.

Features

Resources (Read-only data)

  • todoist://tasks/active - All active (incomplete) tasks
  • todoist://tasks/today - Tasks due today
  • todoist://projects - All projects
  • todoist://labels - All labels

Tools (Actions)

  • create_task - Create new tasks with title, project, labels, priority, and due dates
  • update_task - Update existing task properties
  • complete_task - Mark tasks as complete
  • get_task - Get specific task details
  • list_tasks - List tasks with filters
  • create_project - Create new projects
  • add_comment - Add comments to tasks

Installation

Prerequisites

  • Node.js 18+ (or use asdf/mise)
  • A Todoist account
  • Todoist API token (get yours here)

Setup

  1. Clone the repository

    git clone https://github.com/jimdaga/todoist-mcp-server.git
cd todoist-mcp-server

  2. Install dependencies

    npm install

  3. Configure environment variables

    cp .env.example .env
# Edit .env and add your TODOIST_API_TOKEN

  4. Build the server

    npm run build

Usage

Development Mode

Run the server in development mode with auto-reload:

npm run dev

Production Mode

Build and run:

npm run build
npm start

Integration with Claude Code

Add this configuration to your Claude Code MCP settings file:

macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "todoist": {
      "command": "node",
      "args": ["/absolute/path/to/todoist-mcp-server/dist/index.js"],
      "env": {
        "TODOIST_API_TOKEN": "your_token_here"
      }
    }
  }
}

Or use npm run dev for development:

{
  "mcpServers": {
    "todoist": {
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "/absolute/path/to/todoist-mcp-server",
      "env": {
        "TODOIST_API_TOKEN": "your_token_here"
      }
    }
  }
}

Development

Project Structure

todoist-mcp-server/
├── src/
│   ├── index.ts              # Main MCP server entry point
│   ├── todoist/
│   │   ├── client.ts         # Todoist API wrapper
│   │   ├── types.ts          # TypeScript types
│   │   └── schemas.ts        # Zod validation schemas
│   ├── mcp/
│   │   ├── resources.ts      # Resource handlers
│   │   ├── tools.ts          # Tool handlers
│   │   └── prompts.ts        # Prompt templates
│   └── utils/
│       ├── logger.ts         # Logging utility (stderr only!)
│       ├── errors.ts         # Error classes
│       └── config.ts         # Environment config
├── tests/
│   └── integration.test.ts   # Integration tests
├── package.json
├── tsconfig.json
└── README.md

Development Commands

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode (auto-rebuild)
npm run watch

# Run in development mode
npm run dev

# Run built server
npm start

Important: Logging

This MCP server uses STDIO transport. All logging must go to stderr, never stdout, to avoid corrupting the protocol stream. The logger utility (src/utils/logger.ts) handles this automatically.

❌ Never use: console.log() ✅ Always use: logger.info(), logger.debug(), logger.error()

Environment Variables

  • TODOIST_API_TOKEN (required) - Your Todoist API token
  • LOG_LEVEL (optional) - Logging level: DEBUG, INFO, WARN, ERROR (default: INFO)

Security

  • Never commit your .env file - it contains your API token
  • Store tokens in environment variables or secure secret management
  • The .gitignore excludes .env by default

Development Roadmap

  • Phase 1: Project setup and infrastructure
  • Phase 2: Todoist API integration
  • Phase 3: MCP Resources implementation
  • Phase 4: MCP Tools implementation
  • Phase 5: Testing & documentation
  • Phase 6: Polish & best practices

Contributing

Contributions welcome! This is a learning project for understanding MCP server development.

License

MIT

Resources