christulino/todoist-v1-mcp-server
MCP server for Todoist built on the unified API v1. Stdio transport, 20 tools covering tasks, projects, sections, and labels. No daily reconnection issues.
Ask AI about christulino/todoist-v1-mcp-server
Powered by Claude Β· Grounded in docs
I know everything about christulino/todoist-v1-mcp-server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
todoist-v1-mcp-server
A clean, reliable MCP (Model Context Protocol) server for Todoist β built on the Todoist unified API v1.
Why this exists
The official Todoist web MCP (todoist-ai) has a known persistent disconnection bug on the Anthropic side that requires reconnecting daily. Community alternatives are either built on the deprecated REST API v2 or have schema validation bugs that cause failures when Todoist returns additional fields as their API evolves.
This server:
- Targets the current Todoist API v1 (not deprecated v2)
- Uses stdio transport β no cloud dependency, no daily reconnections
- Uses the modern MCP SDK
registerTool()API (not the deprecatedsetRequestHandlerpattern) - Never enforces strict output schemas on API responses β Todoist can add new fields freely without breaking anything
- Zero SDK wrapper dependency β direct HTTP calls via axios, so there's no intermediary library drifting from the API
Tools (31 total)
Tasks
| Tool | Description |
|---|---|
todoist_get_tasks | List/filter tasks β supports Todoist filter strings like "today", "overdue", "p1", "#ProjectName", "7 days" |
todoist_get_task | Get a single task by ID |
todoist_create_task | Create a task with natural language due dates ("tomorrow", "every monday", etc.) |
todoist_update_task | Update any field; pass clear_due_date: true to remove a due date |
todoist_complete_task | Mark a task as done |
todoist_reopen_task | Reopen a completed task |
todoist_delete_task | Permanently delete a task |
Projects
| Tool | Description |
|---|---|
todoist_get_projects | List all projects |
todoist_get_project | Get a single project by ID |
todoist_create_project | Create a project (with color, view style, parent) |
todoist_update_project | Update a project |
todoist_delete_project | Permanently delete a project and all its tasks |
Sections
| Tool | Description |
|---|---|
todoist_get_sections | List sections within a project |
todoist_create_section | Create a section |
todoist_update_section | Rename a section |
todoist_delete_section | Delete a section |
Labels
| Tool | Description |
|---|---|
todoist_get_labels | List all personal labels |
todoist_create_label | Create a label |
todoist_update_label | Update a label |
todoist_delete_label | Delete a label |
Comments
| Tool | Description |
|---|---|
todoist_get_comments | List comments on a task or project (paginated) |
todoist_get_comment | Get a single comment by ID |
todoist_create_comment | Add a comment to a task or project (Markdown supported) |
todoist_update_comment | Edit an existing comment's content |
todoist_delete_comment | Permanently delete a comment |
Completed tasks (Pro)
| Tool | Description |
|---|---|
todoist_get_completed_tasks | Query completed tasks by completion date (β€3mo) or due date (β€6wk). Pro-only. |
Reminders (Pro)
| Tool | Description |
|---|---|
todoist_get_reminders | List reminders, optionally filtered by task_id. Pro-only. |
todoist_get_reminder | Get a single reminder by ID. Pro-only. |
todoist_create_reminder | Create a relative (minute_offset before due) or absolute reminder. Pro-only. |
todoist_update_reminder | Update reminder timing or notification service. Pro-only. |
todoist_delete_reminder | Permanently delete a reminder. Pro-only. |
Pro-tier handling: Reminders and completed-task queries require a Todoist Pro subscription. If the API returns a Pro-gate error (HTTP 402, or 403 with a
premium/pro/upgrade/paid/subscriptionkeyword), the server returns a clean message explaining the feature requires Pro rather than leaking the raw API error.
Setup
1. Get your Todoist API token
Go to Todoist β Settings β Integrations β Developer and copy your API token.
2. Install and build
git clone https://github.com/christulino/todoist-v1-mcp-server
cd todoist-v1-mcp-server
npm install
npm run build
3. Configure Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"todoist": {
"command": "node",
"args": ["/absolute/path/to/todoist-v1-mcp-server/dist/index.js"],
"env": {
"TODOIST_API_TOKEN": "your_api_token_here"
}
}
}
}
Restart Claude Desktop. You should see "todoist" in the connected MCP servers.
4. Configure Claude Code (optional)
claude mcp add todoist -- node /absolute/path/to/todoist-v1-mcp-server/dist/index.js
Then set the env var:
export TODOIST_API_TOKEN=your_api_token_here
Or add it to your shell profile.
Usage examples
Once connected, Claude can handle natural language like:
- "What's on my plate today?" β uses
todoist_get_taskswithfilter: "today" - "Add a task to call the dentist next Tuesday" β uses
todoist_create_task - "Mark the dentist task as done" β uses
todoist_complete_task - "Show me everything overdue" β uses
todoist_get_taskswithfilter: "overdue" - "Create a project called Home Renovation" β uses
todoist_create_project - "What projects do I have?" β uses
todoist_get_projects
Todoist filter syntax
The filter parameter in todoist_get_tasks supports Todoist's full natural language filter syntax:
| Filter | Meaning |
|---|---|
today | Due today |
overdue | Past due |
7 days | Due in the next 7 days |
p1 | Priority urgent |
#ProjectName | Tasks in a specific project |
@labelname | Tasks with a specific label |
no due date | Tasks without a due date |
today | overdue | Today or overdue (combine with |) |
today & @waiting | Today AND labeled 'waiting' |
Full filter documentation: https://todoist.com/help/articles/introduction-to-filters
Requirements
- Node.js 18+
- A Todoist account (free tier works)
Development
npm run dev # tsx watch mode with auto-reload
npm run build # compile TypeScript
npm start # run compiled server
Testing
The test suite hits the live Todoist API and runs a full CRUD cycle across tasks, projects, sections, labels, comments, and reminders, plus a read-only smoke test for completed-task querying. Reminders and completed-task tests detect Pro-tier gating (HTTP 402/403) and report cleanly when the account is on the Free tier. All test data is prefixed with [mcp-test] and cleaned up automatically.
TODOIST_API_TOKEN=your_token npm test
Your API token is at Todoist β Settings β Integrations β Developer β same token you put in claude_desktop_config.json.
Contributing
PRs welcome. The goal is a minimal, correct implementation that stays current with the Todoist API v1. Priorities:
- Correctness over cleverness
- Permissive output handling (never reject unknown API fields)
- Helpful error messages that tell you what went wrong and how to fix it
License
MIT
