todoist-v1-mcp-server
todoist-v1-mcp-server
Чистый и надежный MCP-сервер (Model Context Protocol) для Todoist, построенный на унифицированном API Todoist v1.
Зачем это нужно
Официальный веб-MCP для Todoist (todoist-ai) имеет известную проблему с постоянными разрывами соединения на стороне Anthropic, что требует ежедневного переподключения. Альтернативы от сообщества либо построены на устаревшем REST API v2, либо имеют ошибки проверки схемы, которые приводят к сбоям, когда Todoist возвращает дополнительные поля по мере развития своего API.
Этот сервер:
Ориентирован на текущий API Todoist v1 (не на устаревший v2)
Использует транспорт stdio — никакой зависимости от облака, никаких ежедневных переподключений
Использует современный API MCP SDK
registerTool()(а не устаревший паттернsetRequestHandler)Никогда не применяет строгие схемы вывода к ответам API — Todoist может свободно добавлять новые поля, не ломая работу сервера
Отсутствие зависимостей от оберток SDK — прямые HTTP-вызовы через axios, поэтому нет промежуточной библиотеки, которая могла бы отставать от API
Related MCP server: MCP Todoist
Инструменты (всего 31)
Задачи
Инструмент | Описание |
| Список/фильтрация задач — поддерживает строки фильтров Todoist, такие как |
| Получить одну задачу по ID |
| Создать задачу с естественным языком для сроков выполнения ( |
| Обновить любое поле; передайте |
| Отметить задачу как выполненную |
| Вернуть выполненную задачу в работу |
| Безвозвратно удалить задачу |
Проекты
Инструмент | Описание |
| Список всех проектов |
| Получить один проект по ID |
| Создать проект (с цветом, стилем отображения, родителем) |
| Обновить проект |
| Безвозвратно удалить проект и все его задачи |
Разделы
Инструмент | Описание |
| Список разделов внутри проекта |
| Создать раздел |
| Переименовать раздел |
| Удалить раздел |
Метки
Инструмент | Описание |
| Список всех личных меток |
| Создать метку |
| Обновить метку |
| Удалить метку |
Комментарии
Инструмент | Описание |
| Список комментариев к задаче или проекту (с пагинацией) |
| Получить один комментарий по ID |
| Добавить комментарий к задаче или проекту (поддерживается Markdown) |
| Редактировать содержимое существующего комментария |
| Безвозвратно удалить комментарий |
Выполненные задачи (Pro)
Инструмент | Описание |
| Запрос выполненных задач по дате завершения (≤3 мес.) или сроку выполнения (≤6 нед.). Только для Pro. |
Напоминания (Pro)
Инструмент | Описание |
| Список напоминаний, опционально отфильтрованных по |
| Получить одно напоминание по ID. Только для Pro. |
| Создать относительное ( |
| Обновить время напоминания или службу уведомлений. Только для Pro. |
| Безвозвратно удалить напоминание. Только для Pro. |
Обработка Pro-уровня: Запросы напоминаний и выполненных задач требуют подписки Todoist Pro. Если API возвращает ошибку Pro-ограничения (HTTP 402 или 403 с ключевым словом
premium/pro/upgrade/paid/subscription), сервер возвращает понятное сообщение о том, что функция требует Pro, вместо вывода необработанной ошибки API.
Настройка
1. Получите ваш API-токен Todoist
Перейдите в Todoist → Настройки → Интеграции → Разработчик и скопируйте ваш API-токен.
2. Установка и сборка
git clone https://github.com/christulino/todoist-v1-mcp-server
cd todoist-v1-mcp-server
npm install
npm run build3. Настройка Claude Desktop
Отредактируйте ~/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"
}
}
}
}Перезапустите Claude Desktop. Вы должны увидеть "todoist" в подключенных MCP-серверах.
4. Настройка Claude Code (опционально)
claude mcp add todoist -- node /absolute/path/to/todoist-v1-mcp-server/dist/index.jsЗатем установите переменную окружения:
export TODOIST_API_TOKEN=your_api_token_hereИли добавьте её в профиль вашей оболочки.
Примеры использования
После подключения Claude может обрабатывать запросы на естественном языке, например:
"Что у меня запланировано на сегодня?" → использует
todoist_get_tasksсfilter: "today""Добавь задачу позвонить стоматологу в следующий вторник" → использует
todoist_create_task"Отметь задачу со стоматологом как выполненную" → использует
todoist_complete_task"Покажи мне всё просроченное" → использует
todoist_get_tasksсfilter: "overdue""Создай проект под названием Ремонт дома" → использует
todoist_create_project"Какие у меня есть проекты?" → использует
todoist_get_projects
Синтаксис фильтров Todoist
Параметр filter в todoist_get_tasks поддерживает полный синтаксис фильтров Todoist на естественном языке:
Фильтр | Значение |
| Срок сегодня |
| Просрочено |
| Срок в ближайшие 7 дней |
| Срочный приоритет |
| Задачи в конкретном проекте |
| Задачи с конкретной меткой |
| Задачи без срока выполнения |
| Сегодня или просрочено (объединение через |
| Сегодня И с меткой 'waiting' |
Полная документация по фильтрам: https://todoist.com/help/articles/introduction-to-filters
Требования
Node.js 18+
Аккаунт Todoist (подходит бесплатный тариф)
Разработка
npm run dev # tsx watch mode with auto-reload
npm run build # compile TypeScript
npm start # run compiled serverТестирование
Набор тестов обращается к реальному API Todoist и выполняет полный цикл CRUD для задач, проектов, разделов, меток, комментариев и напоминаний, а также выполняет smoke-тест (только чтение) для запроса выполненных задач. Тесты напоминаний и выполненных задач обнаруживают ограничения Pro-уровня (HTTP 402/403) и корректно сообщают об этом, если аккаунт находится на бесплатном тарифе. Все тестовые данные имеют префикс [mcp-test] и удаляются автоматически.
TODOIST_API_TOKEN=your_token npm testВаш API-токен находится в разделе Todoist → Настройки → Интеграции → Разработчик — это тот же токен, который вы указали в claude_desktop_config.json.
Вклад в проект
PR приветствуются. Цель — минималистичная, корректная реализация, которая остается актуальной для API Todoist v1. Приоритеты:
Корректность важнее хитроумных решений
Разрешительная обработка вывода (никогда не отклонять неизвестные поля API)
Полезные сообщения об ошибках, которые объясняют, что пошло не так и как это исправить
Лицензия
MIT
Available Tools
20 toolstodoist_complete_taskComplete Todoist TaskAIdempotent
Mark a Todoist task as completed (close it).
This is the standard way to check off a task. For recurring tasks, this advances to the next occurrence rather than permanently removing it.
Use todoist_delete_task to permanently remove a task instead.
Inputs: task_id (required).
todoist_create_labelCreate Todoist LabelA
Create a new personal label in Todoist.
Returns the created label's ID and name. Use the label name (not ID) when assigning labels to tasks with todoist_create_task or todoist_update_task.
Inputs: name (required), color, order, is_favorite.
todoist_create_projectCreate Todoist ProjectA
Create a new project in Todoist.
Color options: berry_red, red, orange, yellow, olive_green, lime_green, green, mint_green, teal, sky_blue, light_blue, blue, grape, violet, lavender, magenta, salmon, charcoal, grey, taupe.
Returns the full created project object including its assigned ID.
Inputs: name (required), parent_id, color, is_favorite, +1 more.
todoist_create_sectionCreate Todoist SectionA
Create a new section within a Todoist project.
Returns the created section's ID and details. Use the section ID when creating tasks (todoist_create_task) to add them directly to this section.
Inputs: name (required), project_id (required), order.
todoist_create_taskCreate Todoist TaskA
Create a new task in Todoist.
The due_string field supports natural language: "tomorrow", "every monday",
"Feb 20", "next week", "in 3 hours", etc.
Priority levels: 1=normal (default), 2=medium, 3=high, 4=urgent.
Returns the full created task object including its assigned ID.
Inputs: content (required), description, project_id, section_id, +6 more.
todoist_delete_labelDelete Todoist LabelADestructive
Permanently delete a personal Todoist label.
The label will be removed from all tasks that currently use it. This cannot be undone.
Inputs: label_id (required).
todoist_delete_projectDelete Todoist ProjectADestructive
Permanently delete a Todoist project and all its tasks. This cannot be undone.
WARNING: All tasks within the project will also be deleted.
Inputs: project_id (required).
todoist_delete_sectionDelete Todoist SectionADestructive
Permanently delete a Todoist section.
Tasks within the section are NOT deleted — they are moved to the parent project (unsectioned). The section itself is permanently removed and cannot be undone.
Inputs: section_id (required).
todoist_delete_taskDelete Todoist TaskADestructive
Permanently delete a Todoist task. This action cannot be undone.
For recurring tasks or tasks you just want to mark as done, use todoist_complete_task instead.
Inputs: task_id (required).
todoist_get_labelsGet Todoist LabelsARead-onlyIdempotent
List all personal labels in the user's Todoist account.
Returns label IDs, names, colors, and sort order. Use label names (not IDs) when creating or updating tasks.
Inputs: response_format.
todoist_get_projectGet Todoist ProjectARead-onlyIdempotent
Retrieve a single Todoist project by its ID.
Returns full project details including name, color, parent project, comment count, sharing status, and view style.
Inputs: project_id (required), response_format.
todoist_get_projectsGet Todoist ProjectsARead-onlyIdempotent
List all projects in the user's Todoist account.
Returns project IDs, names, colors, hierarchy (parent_id for sub-projects), and metadata like whether each project is a favorite or shared.
Use project IDs with todoist_get_tasks to fetch tasks for a specific project.
Inputs: response_format.
todoist_get_sectionsGet Todoist SectionsARead-onlyIdempotent
List all sections within a Todoist project.
Sections are used to organize tasks within a project into groups. Returns section IDs, names, and sort order.
Use section IDs with todoist_get_tasks (section_id param) or todoist_create_task (section_id param) to work with tasks in specific sections.
Inputs: project_id (required), response_format.
todoist_get_taskGet Todoist TaskARead-onlyIdempotent
Retrieve a single Todoist task by its ID.
Returns full task details: content, description, due date, priority, labels, project/section IDs, comment count, and creation timestamp.
Inputs: task_id (required), response_format.
todoist_get_tasksGet Todoist TasksARead-onlyIdempotent
List and filter tasks from Todoist.
Use the filter parameter for powerful natural-language Todoist filters:
"today" → tasks due today
"overdue" → past-due tasks
"7 days" → due in the next 7 days
"p1" → priority 1 (urgent)
"#Work" → tasks in project named Work
"@waiting" → tasks with label 'waiting'
"no due date" → tasks with no due date
Combine with & (AND), | (OR): "today | overdue"
Alternatively, filter by project_id, section_id, or label directly.
Returns task IDs, content, due dates, priorities, labels, and project/section IDs.
Inputs: filter, project_id, section_id, label, +3 more.
todoist_reopen_taskReopen Todoist TaskAIdempotent
Reopen (uncomplete) a previously completed Todoist task.
Useful for tasks that were marked done by mistake or need to be revisited.
Inputs: task_id (required).
todoist_update_labelUpdate Todoist LabelAIdempotent
Update an existing Todoist label. Only include fields to change.
Inputs: label_id (required), name, color, order, +1 more.
todoist_update_projectUpdate Todoist ProjectAIdempotent
Update an existing Todoist project. Only include fields to change.
Inputs: project_id (required), name, color, is_favorite, +1 more.
todoist_update_sectionUpdate Todoist SectionBIdempotent
Rename an existing Todoist section.
Inputs: section_id (required), name (required).
todoist_update_taskUpdate Todoist TaskAIdempotent
Update an existing Todoist task.
Only include the fields you want to change — all fields are optional. To clear a due date, pass clear_due_date: true (sends due_string: "no date" — empty string is silently ignored and due: null returns 400). To remove all labels, pass labels as an empty array [].
Priority: 1=normal, 2=medium, 3=high, 4=urgent.
Inputs: task_id (required), content, description, clear_due_date, +6 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Each tool has a clearly distinct purpose targeting specific resources (tasks, projects, labels, sections) and actions (create, get, update, delete, complete, reopen). Descriptions explicitly differentiate similar tools (e.g., todoist_complete_task vs. todoist_delete_task), eliminating ambiguity.
All tool names follow a consistent verb_noun pattern with the prefix 'todoist_' (e.g., todoist_create_task, todoist_get_labels). The naming is uniform across all 20 tools, using snake_case and clear action verbs aligned with CRUD operations.
With 20 tools, the server provides comprehensive coverage for Todoist's domain, including tasks, projects, labels, and sections. Each tool serves a distinct, necessary function, and the count is well-scoped for managing a task management system without being excessive.
The tool set offers complete CRUD/lifecycle coverage for all core resources (tasks, projects, labels, sections), including specialized actions like complete, reopen, and filtering. There are no obvious gaps; agents can perform all essential operations without dead ends.
Maintenance
Related MCP Connectors
Official Todoist MCP server. Manage tasks and projects. Hosted, no API key needed.
Local-first task manager: create, edit, and complete tasks, projects, and checklists via MCP.
Headless task management for bots, apps and AI agents. Remote MCP server, OAuth or access token.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceA Model Context Protocol server that enables advanced task and project management in Todoist via Claude Desktop and other MCP-compatible clients.99 npm2MIT
- AlicenseBqualityDmaintenanceA Model Context Protocol server implementation compatible with Todoist API, allowing AI agents to interact with task management functionality through standardized MCP tools.518 npm1MIT
- AlicenseAqualityDmaintenanceMCP Server to create and manage tasks, projects, labels and more in Todoist, using their unified v1 API729 npm7GPL 3.0
- AlicenseAqualityDmaintenanceA Python MCP server that enables AI assistants to manage Todoist tasks and projects through the Model Context Protocol. It supports full CRUD operations for tasks and projects, including support for nested projects and Todoist's advanced filter syntax.11MIT