todoist/todoist-mcp

Library for connecting AI agents to Todoist. Includes tools that can be integrated into LLMs,
enabling them to access and modify a Todoist account on the user's behalf.
These tools can be used both through an MCP server, or imported directly in other projects to
integrate them to your own AI conversational interfaces.
## Using tools
### 1. Add this repository as a dependency
sh
npm install @todoist/mcp
This package was previously published as @doist/todoist-mcp.
### 2. Import the tools and plug them to an AI
Here's an example using Vercel's AI SDK.
js
import { findTasksByDate, addTasks } from '@todoist/mcp'
import { TodoistApi } from '@todoist/sdk'
import { streamText } from 'ai'
// Create Todoist API client
const client = new TodoistApi(process.env.TODOIST_API_KEY)
// Helper to wrap tools with the client
function wrapTool(tool, todoistClient) {
return {
...tool,
execute(args) {
return tool.execute(args, todoistClient)
},
const result = streamText({
model: yourModel,
system: 'You are a helpful Todoist assistant',
tools: {
findTasksByDate: wrapTool(findTasksByDate, client),
addTasks: wrapTool(addTasks, client),
},
})
## Using as an MCP server
### Quick Start
You can run the MCP server directly with npx:
bash
npx -p @todoist/mcp todoist-mcp
### Setup Guide
The Todoist MCP server is available as a streamable HTTP service for easy integration with various AI clients:
Primary URL (Streamable HTTP): https://ai.todoist.net/mcp
#### Claude Desktop
1. Open Settings → Connectors → Add custom connector
2. Enter https://ai.todoist.net/mcp and complete OAuth authentication
#### Cursor
Create a configuration file:
Global: ~/.cursor/mcp.json
Project-specific: .cursor/mcp.json
json
"mcpServers": {
"todoist": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://ai.todoist.net/mcp"]
Then enable the server in Cursor settings if prompted.
#### Claude Code (CLI)
The fastest setup is the official Todoist plugin, which wires up the MCP server for you:
bash
/plugin marketplace add todoist/todoist-mcp
/plugin install todoist@doist
OAuth runs in your browser the first time you use a Todoist tool. See Anthropic's plugin docs for more.
If you'd rather configure the MCP server manually, run:
bash
claude mcp add --transport http todoist https://ai.todoist.net/mcp
Then launch claude, execute /mcp, and select the todoist MCP server to authenticate.
#### Gemini CLI
Install the official Todoist extension with Gemini CLI 0.67.0 or later:
bash
gemini extensions install https://github.com/todoist/todoist-mcp
Start or restart Gemini CLI, then run /mcp auth todoist and sign in with your Todoist account. Todoist hosts the server; no API key or local server is needed.
The assistant can read and change your Todoist tasks and projects. Revoke access at any time in Todoist under Settings → Integrations.
#### Visual Studio Code
1. Open Command Palette → MCP: Add Server
2. Select HTTP transport and use:
json
"servers": {
"todoist": {
"type": "http",
"url": "https://ai.todoist.net/mcp"
#### Other MCP Clients
bash
npx -y mcp-remote https://ai.todoist.net/mcp
For more details on setting up and using the MCP server, including creating custom servers, see docs/mcp-server.md.
## Features
A key feature of this project is that tools can be reused, and are not written specifically for use in an MCP server. They can be hooked up as tools to other conversational AI interfaces (e.g. Vercel's AI SDK).