переведено ИИ

Сервер Todoist MCP

MCP-сервер (Model Context Protocol), который соединяет Claude с Todoist для полного управления задачами и проектами через естественный язык.

Установка

Claude Desktop (установка в один клик)

Скачайте todoist-mcp.mcpb из последнего релиза
Дважды щёлкните по файлу (или перетащите в Claude Desktop)
Введите ваш токен API Todoist по запросу
Начните общаться: "Покажи мои проекты в Todoist"

Claude Code / Другие MCP-клиенты

claude mcp add todoist -e TODOIST_API_TOKEN=your_token -- npx @greirson/mcp-todoist

Ручная JSON-конфигурация

Добавьте в конфигурацию вашего MCP-клиента (claude_desktop_config.json, ~/.claude.json и т.д.):

{
"mcpServers": {
  "todoist": {
    "command": "npx",
    "args": ["@greirson/mcp-todoist"],
    "env": {
      "TODOIST_API_TOKEN": "your_api_token_here"
    }
  }
}
}

Местоположения конфигурационных файлов:

Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json
Claude Code: ~/.claude.json

Возможности

19 MCP-инструментов для полного управления Todoist
Управление задачами: Создание, обновление, удаление, выполнение, повторное открытие задач с приоритетами, датами выполнения, метками
Массовые операции: Эффективная обработка нескольких задач
Подзадачи: Иерархическое управление задачами с отслеживанием выполнения
Проекты и секции: Полная поддержка организации
Метки, фильтры, напоминания: Поддержка функций Pro/Business
Естественный язык: Быстрое добавление с использованием парсинга естественного языка Todoist
Режим пробного запуска: Тестирование операций без внесения изменений

Режим пробного запуска

Режим пробного запуска позволяет тестировать операции и автоматизации без внесения каких-либо реальных изменений в вашу рабочую область Todoist. Это идеально подходит для тестирования, отладки, изучения API или проверки автоматизированных скриптов перед их реальным запуском.

Как включить режим пробного запуска

Добавьте DRYRUN=true в вашу конфигурацию окружения:

{
  "mcpServers": {
    "todoist": {
      "command": "npx",
      "args": ["@greirson/mcp-todoist"],
      "env": {
        "TODOIST_API_TOKEN": "your_api_token_here",
        "DRYRUN": "true"
      }
    }
  }
}

Что делает режим пробного запуска

Валидирует операции: Использует реальные данные API для проверки того, что операции выполнятся успешно
Симулирует изменения: Операции создания, обновления, удаления и выполнения симулируются (а не выполняются)
Запросы реальных данных: Операции чтения (получение задач, проектов, меток) используют реальный API
Подробное логирование: Точно показывает, что произошло бы, с понятными префиксами [DRY-RUN]
Обнаружение ошибок: Затеивает те же ошибки, которые возникли бы при реальном выполнении

Примеры использования

Тестирование автоматизаций: Проверка сложных массовых операций перед выполнением
Изучение API: Исследование функциональности без страха нежелательных изменений
Отладка проблем: Понимание того, какие операции были бы выполнены
Безопасные эксперименты: Проба новых рабочих процессов без влияния на ваши реальные задачи
Обучение и демонстрации: Показ работы операций без изменения реальных данных

Пример использования

С включенным режимом пробного запуска операции показывают, что произошло бы:

You: "Create a task called 'Test Task' in my Work project"

Response:
[DRY-RUN] Dry-run mode enabled - mutations will be simulated
[DRY-RUN] Would create task: "Test Task" in project 2203306141, section none

Task created successfully (simulated):
ID: 100001
Title: Test Task
Project: Work (2203306141)
Priority: 4 (Normal)

Поддерживаемые операции

Все 19 MCP-инструментов поддерживают режим пробного запуска:

Создание, обновление, выполнение и удаление задач
Операции с подзадачами и изменения иерархии
Массовые операции над несколькими задачами
Создание проектов и секций
Управление метками
CRUD-операции для напоминаний
Создание комментариев

Отключение режима пробного запуска

Удалите переменную окружения DRYRUN или установите ее значение в false, затем перезапустите Claude Desktop для возврата в обычный режим работы.

Обзор инструментов

Сервер предоставляет 19 MCP-инструментов для полного управления Todoist:

Инструмент	Действия	Описание
`todoist_task`	create, get, update, delete, complete, reopen, quick_add	Полное управление задачами
`todoist_task_bulk`	bulk_create, bulk_update, bulk_delete, bulk_complete	Эффективные операции с множеством задач
`todoist_subtask`	create, bulk_create, convert, promote, hierarchy	Иерархическое управление задачами
`todoist_project`	create, get, update, delete, archive, collaborators	CRUD-операции и совместный доступ к проектам
`todoist_project_ops`	reorder, move_to_parent, get_archived	Расширенные операции с проектами
`todoist_section`	create, get, update, delete, move, reorder, archive	Управление секциями
`todoist_label`	create, get, update, delete, stats	Управление метками с аналитикой
`todoist_comment`	create, get, update, delete	Комментарии к задачам/проектам
`todoist_reminder`	create, get, update, delete	Управление напоминаниями (Pro)
`todoist_filter`	create, get, update, delete	Пользовательские фильтры (Pro)
`todoist_collaboration`	invitations, notifications, workspace operations	Функции командного взаимодействия
`todoist_user`	info, productivity_stats, karma_history	Профиль пользователя и статистика
`todoist_utility`	test_connection, test_features, test_performance, find/merge duplicates	Тестирование и утилиты
`todoist_activity`	get_log, get_events, get_summary	Журнал аудита активности
`todoist_task_ops`	move, reorder, close	Расширенные операции с задачами
`todoist_completed`	get, get_all, get_stats	Получение выполненных задач
`todoist_backup`	list, download	Доступ к автоматическим резервным копиям
`todoist_notes`	create, get, update, delete	Заметки к проектам (совместный доступ)
`todoist_shared_labels`	create, get, rename, remove	Метки рабочей области (Business)

Для подробной документации по инструментам с параметрами и примерами см. TOOLS_REFERENCE.md.

Устранение неполадок

Частые проблемы

"Проекты Todoist не найдены" или ошибки подключения:

Убедитесь, что ваш API-токен верен
Проверьте, что токен правильно установлен в вашем claude_desktop_config.json
Убедитесь, что вокруг токена нет лишних пробелов или кавычек

MCP-сервер не загружается:

Подтвердите, что пакет установлен глобально: npm list -g @greirson/mcp-todoist
Полностью перезапустите Claude Desktop
Проверьте, что путь к файлу конфигурации правильный для вашей операционной системы
Попробуйте полный путь к бинарному файлу mcp-todoist: /Users/USERNAME/.npm-global/bin/mcp-todoist

Ошибки доступа:

На macOS/Linux вам может потребоваться создать каталог конфигурации: mkdir -p ~/.config
Убедитесь, что Claude Desktop имеет разрешение на чтение файла конфигурации

Примеры использования

Настройка проектов и секций

"Show me all my projects"
"Create a new project called 'Work Tasks'"
"Create a section called 'In Progress' in project 12345"
"Show me sections in the Work Tasks project"

Создание и управление задачами

"Create task 'Team Meeting' in project 12345"
"Add task 'Review PR' due tomorrow with labels ['Code Review', 'Urgent']"
"Create high priority task with deadline 2024-12-25"
"Update meeting task to be in section 67890"
"Mark the PR review task as complete"

# Task duration for time blocking
"Create task 'Deep work session' with 90 minute duration"
"Update task 'Meeting' to have a 2 day duration"

# Task identification by ID (more reliable than name search)
"Get task with ID 1234567890"
"Update task ID 1234567890 to priority 4"
"Complete task with ID 1234567890"
"Reopen task with ID 1234567890"
"Delete task ID 1234567890"

Быстрое добавление (Quick Add)

Инструмент Quick Add парсит текст на естественном языке, как в приложении Todoist, поддерживая несколько возможностей в одной команде:

"Quick add: Buy groceries tomorrow #Shopping @errands p1"
"Quick add: Review PR next Monday #Work @code-review p2 //Check error handling"
"Quick add: Call mom {deadline in 3 days}"
"Quick add: Team meeting today at 2pm #Work @meetings with reminder 1 hour before"

Синтаксис Quick Add:

Даты выполнения: Даты на естественном языке, такие как "tomorrow", "next Friday", "Jan 23", "in 3 days"
Проекты: #ProjectName (без пробелов в названиях проектов)
Метки: @label (например, "@urgent", "@work")
Исполнители: +name (для общих проектов)
Приоритет: p1 (срочный), p2, p3, p4 (наименьший)
Крайние сроки: {in 3 days} или {March 15}
Описания: //ваше описание здесь (должно быть в конце)

Управление подзадачами

"Create subtask 'Prepare agenda' under task 'Team Meeting'"
"Create multiple subtasks for 'Launch Project': 'Design UI', 'Write tests', 'Deploy'"
"Convert task 'Code Review' to a subtask of 'Release v2.0'"
"Promote subtask 'Bug Fix' to a main task"
"Show me the task hierarchy for 'Launch Project' with completion tracking"

Массовые операции

"Create multiple tasks for project launch: 'Design mockups', 'Write documentation', 'Set up CI/CD'"
"Update all high priority tasks to be due next week"
"Complete all tasks containing 'review' in project 12345"
"Delete all tasks with priority 1 that are overdue"

Управление комментариями

"Add comment 'This needs urgent attention' to task 'Review PR'"
"Add comment with attachment to task 67890"
"Show all comments for task 'Team Meeting'"
"Get comments for project 12345"

Управление метками

"Show me all my labels"
"Create a new label called 'Urgent' with red color"
"Update the 'Work' label to be blue and mark as favorite"
"Delete the unused 'Old Project' label"
"Get usage statistics for all my labels"

Управление напоминаниями (Pro/Business)

"Show me all my reminders"
"Get reminders for task 'Team Meeting'"
"Create a reminder for task 'Review PR' 30 minutes before due"
"Create an absolute reminder for task 12345 at 2024-12-25T09:00:00Z"
"Update reminder 67890 to trigger at 10:00 instead"
"Delete reminder 67890"

Поиск задач

"Show all my tasks"
"List high priority tasks due this week"
"Get tasks in project 12345"

Тестирование и валидация

"Test my Todoist connection"
"Run basic tests on all Todoist features" // Default: read-only API tests
"Run enhanced tests on all Todoist features" // Full CRUD testing with cleanup
"Benchmark Todoist API performance with 10 iterations"
"Validate that all MCP tools are working correctly"

Пробный тест

При включенном режиме пробного запуска (DRYRUN=true) используйте обычные команды — они будут автоматически симулироваться:

"Create a test task with priority 1"
"Update all overdue tasks to be due tomorrow"
"Delete all completed tasks in project 12345"
"Create 5 subtasks under task 'Project Planning'"

Все эти операции будут проверяться на ваших реальных данных, но не внесут никаких изменений.

Разработка

Сборка из исходников

# Clone the repository
git clone https://github.com/greirson/mcp-todoist.git

# Navigate to directory
cd mcp-todoist

# Install dependencies
npm install

# Build the project
npm run build

Команды разработки

# Watch for changes and rebuild
npm run watch

# Run tests
npm run test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

# Check formatting
npm run format:check

Архитектура

Кодовая база следует чистой, модульной архитектуре, разработанной для удобства сопровождения и масштабируемости:

Основная структура

src/index.ts: Основная точка входа сервера с маршрутизацией запросов
src/types.ts: Определения типов и интерфейсов TypeScript
src/type-guards.ts: Функции проверки типов во время выполнения
src/validation.ts: Валидация и санитализация входных данных
src/errors.ts: Пользовательские типы ошибок со структурированной обработкой
src/cache.ts: Кэширование в памяти для оптимизации производительности

Модульная организация инструментов

src/tools/: Определения MCP-инструментов по предметным областям, организованные по функциональности:
task-tools.ts - Управление задачами (9 инструментов)
subtask-tools.ts - Операции с подзадачами (5 инструментов)
project-tools.ts - Управление проектами/разделами (4 инструмента)
comment-tools.ts - Операции с комментариями (2 инструмента)
label-tools.ts - Управление метками (5 инструментов)
reminder-tools.ts - Операции с напоминаниями (4 инструмента)
test-tools.ts - Тестирование и валидация (3 инструмента)
index.ts - Централизованный экспорт

Обработчики бизнес-логики

src/handlers/: Модули бизнес-логики, разделенные по предметным областям:
task-handlers.ts - CRUD-операции с задачами и массовые операции
subtask-handlers.ts - Иерархическое управление задачами
project-handlers.ts - Операции с проектами и разделами
comment-handlers.ts - Создание и получение комментариев
label-handlers.ts - CRUD-операции с метками и статистика
reminder-handlers.ts - CRUD-операции с напоминаниями через Sync API
test-handlers.ts - Инфраструктура тестирования API
test-handlers-enhanced/ - Комплексная среда для CRUD-тестирования

Утилитарные модули

src/utils/: Общие вспомогательные функции:
api-helpers.ts - Утилиты для обработки ответов API
error-handling.ts - Централизованное управление ошибками
parameter-transformer.ts - Преобразование параметров из формата MCP в формат SDK Todoist
dry-run-wrapper.ts - Реализация режима пробного запуска

Журнал изменений

См. CHANGELOG.md для подробной истории всех изменений.

Для руководств по миграции и информации о обратно несовместимых изменениях см. полный журнал изменений.

Вклад

Приветствуется вклад! Этот проект активно поддерживается, и я ценю интерес сообщества к его улучшению.

Замечание об участии с помощью ИИ

Я использую Claude Code как часть своего собственного рабочего процесса разработки — помощь ИИ при написании кода является обычной частью создания этого проекта. Я鼓励 contributors использовать любые инструменты, которые повышают их продуктивность, включая помощников по программированию на основе ИИ.

Тем не менее, инструменты ИИ делают очень простым генерацию больших объемов кода, который выглядит правильно, но вводит тонкие проблемы: неправильные соответствия API, регрессии производительности, нарушение изменений типов или расширение范围 (scope creep), которое объединяет несвязанные функции. Я видел PR, которые заменяют префикс URL, не осознавая, что изменились сами пути API, или добавляют постраничную навигацию, извлекая каждую страницу каждый раз без сохранения параметра limit.

По этой причине каждый PR подвергается тщательному архитектурному обзору. Это не о контроле доступа — это о поддержании базы кода, от которой зависят сотни людей через свои MCP-клиенты. PR, которые выглядят как непроверенный вывод ИИ, получат подробную обратную связь о том, что нужно изменить и почему, чтобы вы могли извлечь урок и повторить попытку.

Требования к PR

Прежде чем отправить pull request, пожалуйста, убедитесь:

Одна проблема на PR. Исправление ошибки — это один PR. Новая функция — другой. Обновление документации — третий. Если ваш diff затрагивает 40+ файлов в несвязанных функциях, его необходимо разделить. PR со смешанными областями будут возвращены для разделения.
Вы понимаете, что делает ваш код. Если инструмент ИИ его написал, критически прочитайте перед отправкой. Можете ли вы объяснить, почему каждое изменение необходимо? Смогли бы вы отладить его, если он сломался? Если нет, он не готов.
Тесты включены или обновлены. Новые функции требуют тестов. Исправления ошибок требуют теста, который бы обнаружил эту ошибку. Если вы изменяете конечные точки API, проверьте их работу с реальным API — не просто доверяйте тому, что замены URL достаточно.
Выполнена ручная проверка. Запустите npm run build и npm test локально. Если вы изменяете код интеграции с API, протестируйте его со своим аккаунтом Todoist (режим пробного запуска доступен с DRYRUN=true). Включите доказательство проверки в описание вашего PR.
CI должен пройти. PR с непрошедшими проверками CI не будут рассматриваться, пока они не станут зелеными.

Что делает PR хорошим

Понятное, описательное название и тело, объясняющее что и почему
Сосредоточенный diff, который легко проверять (идеально менее 200 измененных строк)
Тесты, демонстрирующие, что изменение работает
Обновленная документация, если изменение затрагивает поведение, видимое пользователю
Отсутствие несвязанных изменений форматирования, рефакторинга или улучшений "заодно"

Как начать

Fork репозитория
Создайте ветку feature от main
Внесите изменения, следуя приведенным выше руководствам
Запустите npm run build && npm test && npm run lint для проверки
Отправьте свой PR с четким описанием

Если вы не уверены, желательно ли изменение или как его лучше реализовать, сначала откройте issue для обсуждения. Это экономит время всем и помогает согласовать подход до написания кода.

Лицензия

Этот проект лицензирован по лицензии MIT — см. файл LICENSE для подробностей.

Проблемы и поддержка

Если вы столкнулись с какими-либо проблемами или вам нужна поддержка, пожалуйста, создайте issue в репозитории на GitHub.

Todoist MCP

Сервер Todoist MCP

Установка

Claude Desktop (установка в один клик)

Claude Code / Другие MCP-клиенты

Возможности

Режим пробного запуска

Как включить режим пробного запуска

Что делает режим пробного запуска

Примеры использования

Пример использования

Поддерживаемые операции

Отключение режима пробного запуска

Обзор инструментов

Устранение неполадок

Частые проблемы

Примеры использования

Настройка проектов и секций

Создание и управление задачами

Быстрое добавление (Quick Add)

Управление подзадачами

Массовые операции

Управление комментариями

Управление метками

Управление напоминаниями (Pro/Business)

Поиск задач

Тестирование и валидация

Пробный тест

Разработка

Сборка из исходников

Команды разработки

Архитектура

Основная структура

Модульная организация инструментов

Обработчики бизнес-логики

Утилитарные модули

Журнал изменений

Вклад

Замечание об участии с помощью ИИ

Требования к PR

Что делает PR хорошим

Как начать

Лицензия

Проблемы и поддержка

Комментарии