Skip to content

mcp-server.md

Latest commit

 

History

History
184 lines (131 loc) · 7.44 KB

mcp-server.md

File metadata and controls

184 lines (131 loc) · 7.44 KB
Raw

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-mcp

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-mcp
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-mcp'
import { StdioServerTransport } from '@modelcontextprotocol/server/stdio'

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-mcp": {
            "type": "stdio",
            "command": "npx",
            "args": ["@doist/todoist-mcp"],
            "env": {
                "TODOIST_API_KEY": "your-todoist-token-here"
            }
        }
    }
}

Using local installation

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

{
    "mcpServers": {
        "todoist-mcp-local": {
            "type": "stdio",
            "command": "node",
            "args": ["/Users/<your_user_name>/code/todoist-mcp/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 a local HTTP service. This is useful as an alternative to the hosted service at ai.todoist.net/mcp, especially if you experience frequent session disconnections (#239).

Important

The standalone HTTP server runs every MCP tool with the TODOIST_API_KEY supplied by the operator. It binds to 127.0.0.1 by default and is intended for local MCP clients. Requests to /mcp have their Host and Origin headers validated against a trusted-hostname allowlist (DNS-rebinding protection), so loopback clients work out of the box (/health is exempt so deployment health probes keep working). Do not expose it to a LAN or the public internet unless you add your own trusted network and authentication controls — and when you do, set ALLOWED_HOSTS to the hostnames your clients use.

Quick Start with npx

TODOIST_API_KEY=your-key npx -p @doist/todoist-mcp todoist-mcp-http

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

# Explicitly expose on all interfaces. Only do this behind trusted network/auth controls.
# Set ALLOWED_HOSTS to the hostnames clients use, otherwise their requests are rejected with 403.
TODOIST_API_KEY=your-key HOST=0.0.0.0 ALLOWED_HOSTS=mcp.example.lan npx -p @doist/todoist-mcp todoist-mcp-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. MCP tool calls run as this Todoist user.
HOST 127.0.0.1 HTTP bind host. Use non-loopback hosts only behind trusted network/auth controls.
ALLOWED_HOSTS (optional) Comma-separated extra hostnames trusted in the Host/Origin headers (DNS-rebinding protection), in addition to the loopback defaults (localhost, 127.0.0.1, [::1]). Required when HOST=0.0.0.0 so LAN clients' hostnames are accepted. IPv6 entries must be bracketed, e.g. [2001:db8::1].
PORT 3000 HTTP server port
TODOIST_BASE_URL (optional) Custom Todoist API base URL

Local Development

PORT=8080 npm run dev:http

This will expose the service at http://127.0.0.1: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://127.0.0.1:3000/mcp"]
        }
    }
}

Health Check

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

  • Server status
curl http://127.0.0.1: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 app is built as a single HTML file in dist/mcp-apps/index.html.
  • The MCP server reads that HTML at startup, hashes it, and uses a ui://...@<hash> URI for cache-busting.
  • npm run build builds both the server bundle and the MCP Apps HTML.
  • npm run dev watches both builds and restarts the server when JS or HTML changes.