Todoist MCP Server

Библиотека для подключения AI-агентов к Todoist. Включает инструменты, которые можно интегрировать в LLMs, позволяя им получать доступ к учётной записи Todoist и управлять ею от имени пользователя.

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

Использование инструментов

1. Добавьте этот репозиторий в зависимости проекта

npm install @doist/todoist-mcp

2. Импортируйте инструменты и подключите их к AI

Ниже приведён пример с использованием Vercel's AI SDK.

import { findTasksByDate, addTasks } from '@doist/todoist-mcp'
import { TodoistApi } from '@doist/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),
    },
})

Использование как MCP сервера

Быстрый старт

Вы можете запустить MCP сервер напрямую через npx:

npx @doist/todoist-mcp

Руководство по настройке

Todoist MCP сервер доступен как потоковый HTTP-сервис для легкой интеграции с различными AI-клиентами:

Основной URL (Streamable HTTP): https://ai.todoist.net/mcp

Claude Desktop

Откройте Settings → Connectors → Add custom connector
Введите https://ai.todoist.net/mcp и завершите OAuth-аутентификацию

Cursor

Создайте конфигурационный файл:

Global: ~/.cursor/mcp.json
Project-specific: .cursor/mcp.json

{
    "mcpServers": {
        "todoist": {
            "command": "npx",
            "args": ["-y", "mcp-remote", "https://ai.todoist.net/mcp"]
        }
    }
}

Затем включите сервер в настройках Cursor, если будет запрошено.

Claude Code (CLI)

Самая быстрая настройка — официальный плагин Todoist, который подсоединит MCP сервер за вас:

/plugin marketplace add doist/todoist-mcp
/plugin install todoist@doist

OAuth будет запущен в браузере при первом использовании инструмента Todoist. См. документацию плагина Anthropic для получения дополнительной информации.

Если вы предпочитаете настроить MCP сервер вручную, выполните:

claude mcp add --transport http todoist https://ai.todoist.net/mcp

Затем запустите claude, выполните /mcp и выберите MCP сервер todoist для аутентификации.

Visual Studio Code

Откройте Command Palette → MCP: Add Server
Выберите HTTP-транспорт и используйте:

{
    "servers": {
        "todoist": {
            "type": "http",
            "url": "https://ai.todoist.net/mcp"
        }
    }
}

Другие MCP Клиенты

npx -y mcp-remote https://ai.todoist.net/mcp

Для получения дополнительных сведений по настройке и использованию MCP сервера, включая создание кастомных серверов, см. docs/mcp-server.md.

Особенности

Ключевая особенность проекта в том, что инструменты можно повторно использовать и они не написаны специально для MCP сервера. Их можно подключать как инструменты к другим интерфейсам разговорного AI (например, к Vercel's AI SDK).

Проект находится на ранней стадии разработки. Ожидайте появления новых и/или более качественных инструментов в ближайшее время.

Тем не менее, наша цель — предоставить небольшой набор инструментов, который обеспечивает полноценные рабочие процессы, а не только атомарные действия, сочетая гибкость и эффективность для LLMs.

Для нашего видения дизайна, руководств и паттернов разработки смотрите docs/tool-design.md.

Доступные инструменты

Для полного списка доступных инструментов см. директорию src/tools.

OpenAI MCP Compatibility

Этот сервер включает инструменты search и fetch, которые следуют OpenAI MCP specification, обеспечивая бесшовную интеграцию с протоколом MCP от OpenAI. Эти инструменты возвращают результаты в JSON-формате, оптимизированном под требования OpenAI, при этом оставаясь совместимыми с более широкой экосистемой MCP.

Зависимости

MCP сервер с использованием официального @modelcontextprotocol/sdk
Todoist Typescript API клиент @doist/todoist-sdk

Настройка MCP сервера

См. docs/mcp-server.md для полного руководства по настройке MCP сервера.

Локальная настройка разработки

См. docs/dev-setup.md для полного руководства по настройке и CONTRIBUTING.md для рабочих процессов вкладчиков и проверок качества.

MCP Apps

В проекте предусмотрена поддержка MCP Apps – интерактивные UI-виджеты, выводимые прямо в интерфейсах AI-чата. Виджеты дают богатые визуальные представления результатов инструментов (например, списков задач) вместо обычного текста.

См. docs/mcp-apps.md для архитектуры виджетов, конвейера сборки и рабочих процессов разработки.

Быстрый старт

После клонирования и настройки репозитория:

npm start - сборка и запуск MCP-инспектора для тестирования
npm run dev - режим разработки с авто-пересборкой и перезапуском
npm run tool:list - список доступных инструментов для прямого выполнения
npm run tool -- <tool-name> '<json-args>' - запустить инструмент напрямую без MCP

При использовании npm run tool добавляйте -- перед аргументами инструмента, чтобы npm передал их в scripts/run-tool.ts.

Пример проверки перед операциями записи:

npm run tool -- user-info '{}'

Это подтверждает, к какому именно Todoist-аккаунту подключён текущий TODOIST_API_KEY.

run-tool использует TODOIST_API_KEY из вашего .env файла (созданного из .env.example через npm run setup). Используйте тестовый аккаунт или временный проект при выполнении операций записи, чтобы не изменять реальные данные.

Вклад

См. CONTRIBUTING.md для:

рабочего процесса разработки
запуска инструментов напрямую с scripts/run-tool.ts
тестирования и контроля качества
соглашений по коммитам

Выпуск

Этот проект использует release-please для автоматизации управления версиями и публикации пакетов.

Как это работает

Делайте изменения с использованием Conventional Commits:
- feat: для новых функций (микро-версия)
- fix: для исправления ошибок (патч-версия)
- feat!: или fix!: для изменений, ломающих обратную совместимость (мажорная версия)
- docs: для изменений в документации
- chore: для задач обслуживания
- ci: для изменений в CI
При отправке коммитов в ветку main:

Release-please автоматически создаёт/обновляет PR на выпуск
- PR включает увеличение версии и обновления changelog
- Просмотрите PR и слейте, когда будете готовы
После слияния PR выпуска:

Автоматически создаётся новый релиз на GitHub
- Создается новый тег
- Запускается workflow публикации
- Пакет публикуется в npm