Skip to content

Latest commit

 

History

History
180 lines (129 loc) · 4.71 KB

mcp-server.md

File metadata and controls

180 lines (129 loc) · 4.71 KB

MCP Server Setup

This document outlines the steps necessary to run this MCP server and connect to an MCP host application, such as Claude Desktop or Cursor.

Quick Setup

The easiest way to use this MCP server is with npx:

npx @doist/todoist-ai

You'll need to set your Todoist API key as an environment variable TODOIST_API_KEY.

Local Development Setup

Start by cloning this repository and setting it up locally, if you haven't done so yet.

git clone https://github.com/Doist/todoist-ai
npm run setup

To test the server locally before connecting it to an MCP client, you can use:

npm start

This will build the project and run the MCP inspector for manual testing.

Creating a Custom MCP Server

For convenience, we also include a function that initializes an MCP Server with all the tools available:

import { getMcpServer } from "@doist/todoist-ai";

async function main() {
  const server = getMcpServer({ todoistApiKey: process.env.TODOIST_API_KEY });
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

Then, proceed depending on the MCP protocol transport you'll use.

Using Standard I/O Transport

Quick Setup with npx

Add this section to your mcp.json config in Claude, Cursor, etc.:

{
  "mcpServers": {
    "todoist-ai": {
      "type": "stdio",
      "command": "npx",
      "args": ["@doist/todoist-ai"],
      "env": {
        "TODOIST_API_KEY": "your-todoist-token-here"
      }
    }
  }
}

Using local installation

Add this todoist-ai-tools section to your mcp.json config in Cursor, Claude, Raycast, etc.

{
  "mcpServers": {
    "todoist-ai-tools": {
      "type": "stdio",
      "command": "node",
      "args": ["/Users/<your_user_name>/code/todoist-ai-tools/dist/main.js"],
      "env": {
        "TODOIST_API_KEY": "your-todoist-token-here"
      }
    }
  }
}

Update the configuration above as follows

  • Replace TODOIST_API_KEY with your Todoist API token.
  • Replace the path in the args array with the correct path to where you cloned the repository

Note

You may also need to change the command, passing the full path to your node binary, depending one how you installed node.

Using Streamable HTTP Server Transport

You can run the MCP server as an HTTP service with configurable session timeouts. This is useful as an alternative to the hosted service at ai.todoist.net/mcp, especially if you experience frequent session disconnections (#239).

Quick Start with npx

# Default: 30 minute session timeout
TODOIST_API_KEY=your-key npx -p @doist/todoist-ai todoist-ai-http

# Custom timeout: 1 hour (3600000ms)
TODOIST_API_KEY=your-key SESSION_TIMEOUT_MS=3600000 npx -p @doist/todoist-ai todoist-ai-http

# Custom port
TODOIST_API_KEY=your-key PORT=8080 npx -p @doist/todoist-ai todoist-ai-http

Running from Source

After cloning the repository:

# Install dependencies and build
npm install && npm run build

# Run the HTTP server
TODOIST_API_KEY=your-key npm run start:http

# Or directly with node
TODOIST_API_KEY=your-key node dist/main-http.js

Environment Variables

Variable Default Description
TODOIST_API_KEY (required) Your Todoist API key
PORT 3000 HTTP server port
SESSION_TIMEOUT_MS 1800000 Session timeout in milliseconds (30 min default)
TODOIST_BASE_URL (optional) Custom Todoist API base URL

Local Development

PORT=8080 npm run dev:http

This will expose the service at http://localhost:8080/mcp with hot-reload.

Connecting MCP Clients

MCP host applications can connect via the mcp-remote bridge:

{
  "mcpServers": {
    "todoist-mcp-http": {
      "type": "stdio",
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:3000/mcp"]
    }
  }
}

Health Check

The HTTP server exposes a health check endpoint at /health that returns:

  • Server status
  • Number of active sessions
  • Configured session timeout
curl http://localhost:3000/health

Note

You may also need to change the command, passing the full path to your npx binary, depending on how you installed node.

MCP Apps (task-list) build pipeline

  • The task list widget is bundled and inlined at Vite build time via a custom plugin (virtual:todoist-ai-widgets).
  • The plugin uses BUILD_TIMESTAMP (from process.env.BUILD_TIMESTAMP or auto-generated) to cache-bust the widget URI (e.g., task-list-<timestamp>.html).
  • The final HTML is embedded in the JS bundle; the runtime MCP server does not read from dist/ to find widget files.
  • npm run build is sufficient