Todoist MCP

Сервер Todoist MCP

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

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

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

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

npm install @doist/todoist-mcp

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

Вот пример использования Vercel 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 (потоковый HTTP): https://ai.todoist.net/mcp

Claude Desktop

1. Откройте Настройки → Подключения → Добавить пользовательское подключение
2. Введите https://ai.todoist.net/mcp и завершите OAuth-аутентификацию

Cursor

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

• Глобальный: ~/.cursor/mcp.json
• Для конкретного проекта: .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

1. Откройте Палитру команд → MCP: Добавить сервер
2. Выберите 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 AI SDK).

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

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

О нашей философии дизайна, рекомендациях и паттернах разработки см. docs/tool-design.md.

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

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

Совместимость с OpenAI MCP

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

Зависимости

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

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

Полные инструкции по настройке MCP-сервера см. в docs/mcp-server.md.

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

Полные инструкции по настройке см. в docs/dev-setup.md, а рабочие процессы для контрибьюторов и проверки качества — в CONTRIBUTING.md.

MCP-приложения

Этот проект включает поддержку MCP-приложений — интерактивных 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 для автоматизации управления версиями и публикации пакетов.

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

1. Вносите изменения, используя Conventional Commits:

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

2. Когда коммиты отправляются в main:

   • Release-please автоматически создает/обновляет PR релиза
   • PR включает увеличение версии и обновление журнала изменений
   • Проверьте PR и объедините его, когда будет готово

3. После объединения PR релиза:

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