Ticktick Api Mcp (typescript)

TickTick MCP Server (TypeScript)

Cервер Model Context Protocol (MCP) для интеграции с TickTick API, написанный на TypeScript.

🚀 Кстати! Если вы работаете с ИИ и автоматизацией — обратите внимание на polza.ai — российский агрегатор API нейросетей. Никаких VPN, оплата российской картой, интеграция с n8n/Make/Zapier. Идеально для ваших AI-проектов! 🇷🇺

Возможности

• 🔑 Простая авторизация - используйте access token из переменных окружения
• 📋 Управление проектами - создание, просмотр и удаление проектов (включая поддержку типов TASK и NOTE)
• ✅ Управление задачами - создание, обновление, завершение и удаление задач
• 🛠️ Отдельный скрипт для получения токена - простой способ получить access token
• 📊 Информация о конфигурации - просмотр текущих настроек через ресурсы
• 🔌 Бесшовная интеграция с Claude и другими MCP клиентами
• 🐳 Docker поддержка - запуск в контейнере с HTTP доступом
• ✅ Надежная валидация - автоматическая проверка и преобразование данных
• 🔄 Retry логика - автоматические повторы при временных ошибках
• 📝 Детальное логирование - подробные логи для отладки

Предварительные требования

• Node.js 18 или выше
• npm или yarn
• TickTick API credentials (Client ID, Client Secret)

Установка

1. Клонируйте репозиторий:

git clone https://github.com/polza-ai/ticktick-mcp-ts.git
cd ticktick-mcp-ts

2. Установите зависимости:

npm install

3. Соберите проект:

npm run build

Аутентификация с TickTick

Этот сервер использует OAuth2 для аутентификации с TickTick. Процесс настройки простой:

Шаг 1: Регистрация приложения

1. Зарегистрируйте ваше приложение в TickTick Developer Center
   • Установите redirect URI как http://localhost:8080/callback
   • Запишите ваш Client ID и Client Secret

Шаг 2: Настройка переменных окружения

2. Создайте файл .env на основе .env.example:

# TickTick API credentials (ТОЛЬКО для получения access token)
# Получите их на https://developer.ticktick.com/manage
TICKTICK_CLIENT_ID=your_client_id_here
TICKTICK_CLIENT_SECRET=your_client_secret_here

# TickTick Access Token (ОБЯЗАТЕЛЬНО для работы)
# Получите его запустив 'npm run get-token'
TICKTICK_ACCESS_TOKEN=your_access_token_here

# TickTick API endpoints (значения по умолчанию)
TICKTICK_BASE_URL=https://api.ticktick.com/open/v1
TICKTICK_AUTH_URL=https://ticktick.com/oauth/authorize
TICKTICK_TOKEN_URL=https://ticktick.com/oauth/token

# Для Dida365 (китайская версия), раскомментируйте и используйте вместо:
# TICKTICK_BASE_URL=https://api.dida365.com/open/v1
# TICKTICK_AUTH_URL=https://dida365.com/oauth/authorize
# TICKTICK_TOKEN_URL=https://dida365.com/oauth/token

Шаг 3: Получение токена доступа

3. Запустите процесс аутентификации:

npm run get-token

Это:

• Запустит локальный сервер на порту 8080
• Откроет окно браузера для входа в TickTick
• Автоматически сохранит ваши токены доступа в файл .env

Шаг 4: Тестирование конфигурации

4. Протестируйте вашу конфигурацию:

npm test

Это проверит, что ваши учетные данные TickTick работают корректно и покажет реальные данные из вашего аккаунта.

Аутентификация с Dida365

滴答清单 - Dida365 - это китайская версия TickTick, и процесс аутентификации аналогичен TickTick:

1. Зарегистрируйте ваше приложение в Dida365 Developer Center

   • Установите redirect URI как http://localhost:8080/callback
   • Запишите ваш Client ID и Client Secret

2. Добавьте переменные окружения в ваш файл .env:

   TICKTICK_BASE_URL=https://api.dida365.com/open/v1
   TICKTICK_AUTH_URL=https://dida365.com/oauth/authorize
   TICKTICK_TOKEN_URL=https://dida365.com/oauth/token
   

3. Следуйте тем же шагам аутентификации, что и для TickTick

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

Локальный запуск

С Claude for Desktop

1. Установите Claude for Desktop

2. Отредактируйте файл конфигурации Claude for Desktop:

   macOS:

   nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
   

   Windows:

   notepad %APPDATA%\Claude\claude_desktop_config.json
   

3. Добавьте конфигурацию TickTick MCP сервера, используя абсолютные пути:

   {
      "mcpServers": {
         "ticktick": {
            "command": "node",
            "args": ["/absolute/path/to/ticktick-mcp-ts/dist/index.js"],
            "env": {
              "TICKTICK_ACCESS_TOKEN": "your_access_token_here",
              "TICKTICK_BASE_URL": "https://api.ticktick.com/open/v1"
            }
         }
      }
   }
   

4. Перезапустите Claude for Desktop

После подключения вы увидите инструменты TickTick MCP сервера доступными в Claude, обозначенные иконкой 🔨 (tools).

🐳 Запуск в Docker контейнере

Проект поддерживает запуск в Docker контейнере с использованием supergateway для HTTP доступа к MCP серверу.

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

1. Убедитесь, что у вас есть .env файл с необходимыми переменными:

   TICKTICK_ACCESS_TOKEN=your_access_token_here
   TICKTICK_BASE_URL=https://api.ticktick.com/open/v1
   SUPERGATEWAY_PORT=8002
   

2. Запустите контейнер с помощью Docker Compose:

   docker-compose up -d
   

3. Или соберите и запустите вручную:

   # Сборка образа
   docker build -t ticktick-mcp .
   
   # Запуск контейнера
   docker run -d \
     --name ticktick-mcp \
     -p 8002:8002 \
     -e TICKTICK_ACCESS_TOKEN=your_access_token_here \
     -e TICKTICK_BASE_URL=https://api.ticktick.com/open/v1 \
     -e SUPERGATEWAY_PORT=8002 \
     ticktick-mcp
   

Использование с Claude через HTTP

После запуска контейнера, MCP сервер будет доступен по HTTP на порту 8002. Добавьте следующую конфигурацию в Claude for Desktop:

{
   "mcpServers": {
      "ticktick": {
         "command": "npx",
         "args": ["-y", "@modelcontextprotocol/server-everything", "http://localhost:8002/mcp"]
      }
   }
}

Docker команды для управления

# Просмотр логов
docker-compose logs -f ticktick-mcp

# Остановка сервиса
docker-compose down

# Перезапуск сервиса
docker-compose restart

# Обновление образа
docker-compose down
docker-compose build --no-cache
docker-compose up -d

Переменные окружения для Docker

Переменная	Описание	По умолчанию
SUPERGATEWAY_PORT	Порт для HTTP доступа к MCP серверу	8002
TICKTICK_ACCESS_TOKEN	Access token для TickTick API	Обязательно
TICKTICK_BASE_URL	Base URL для TickTick API	https://api.ticktick.com/open/v1
TICKTICK_CLIENT_ID	Client ID (только для получения токена)	-
TICKTICK_CLIENT_SECRET	Client Secret (только для получения токена)	-

Преимущества Docker запуска

• 🔒 Изолированная среда - сервер работает в отдельном контейнере
• 🌐 HTTP доступ - можно подключаться к серверу по сети
• 🔄 Автоматический перезапуск - контейнер перезапускается при сбоях
• 📦 Простое развертывание - один контейнер содержит все зависимости
• 🚀 Масштабируемость - легко запустить несколько экземпляров

Проверка работы Docker контейнера

# Проверка статуса контейнера
docker ps | grep ticktick-mcp

# Проверка доступности HTTP endpoint
curl http://localhost:8002/health

# Тест MCP подключения
curl -X POST http://localhost:8002/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0.0"}}}'

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

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

get_projects

Получить все проекты пользователя TickTick

• Параметры: Нет параметров

create_project

Создать новый проект в TickTick

• Параметры:
  • name (обязательно) - Название проекта
  • color (опционально) - Цвет проекта (например, #FF0000)
  • viewMode (опционально) - Режим отображения: "list", "kanban", "timeline"
  • sortOrder (опционально) - Порядок сортировки проекта (число)
  • kind (опционально) - Тип проекта: "TASK" (по умолчанию) или "NOTE"

update_project

Обновить существующий проект в TickTick

• Параметры:
  • projectId (обязательно) - ID проекта
  • name (опционально) - Новое название проекта
  • color (опционально) - Новый цвет проекта (например, #FF0000)
  • viewMode (опционально) - Новый режим отображения: "list", "kanban", "timeline"
  • sortOrder (опционально) - Новый порядок сортировки проекта (число)
  • kind (опционально) - Новый тип проекта: "TASK" или "NOTE"

delete_project

Удалить проект из TickTick

• Параметры:
  • projectId (обязательно) - ID проекта

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

get_project_tasks

Получить все задачи конкретного проекта

• Параметры:
  • projectId (обязательно) - ID проекта

get_task

Получить детали конкретной задачи

• Параметры:
  • projectId (обязательно) - ID проекта
  • taskId (обязательно) - ID задачи

create_task

Создать новую задачу в TickTick

• Параметры:
  • title (обязательно) - Название задачи
  • projectId (обязательно) - ID проекта
  • content (опционально) - Описание задачи
  • desc (опционально) - Дополнительное описание
  • isAllDay (опционально) - Задача на весь день (boolean)
  • startDate (опционально) - Дата начала (ISO 8601 формат)
  • dueDate (опционально) - Срок выполнения (ISO 8601 формат)
  • timeZone (опционально) - Временная зона (например, America/Los_Angeles)
  • reminders (опционально) - Массив напоминаний (например, ['TRIGGER:P0DT9H0M0S'])
  • repeatFlag (опционально) - Правило повторения (например, 'RRULE:FREQ=DAILY;INTERVAL=1')
  • priority (опционально) - Приоритет: "none", "low", "medium", "high"
  • sortOrder (опционально) - Порядок сортировки (число)
  • items (опционально) - Массив подзадач:
    • title (обязательно) - Название подзадачи
    • status (опционально, по умолчанию 0) - Статус: 0=Normal, 1=Completed
    • isAllDay (опционально) - Подзадача на весь день
    • startDate (опционально) - Дата начала подзадачи
    • timeZone (опционально) - Временная зона подзадачи
    • sortOrder (опционально) - Порядок сортировки подзадачи

update_task

Обновить существующую задачу

• Параметры:
  • taskId (обязательно) - ID задачи
  • projectId (обязательно) - ID проекта
  • title (опционально) - Новое название задачи
  • content (опционально) - Новое описание задачи
  • desc (опционально) - Новое дополнительное описание
  • isAllDay (опционально) - Задача на весь день (boolean)
  • startDate (опционально) - Новая дата начала (ISO 8601 формат)
  • dueDate (опционально) - Новый срок выполнения (ISO 8601 формат)
  • timeZone (опционально) - Новая временная зона
  • reminders (опционально) - Новые напоминания
  • repeatFlag (опционально) - Новое правило повторения
  • priority (опционально) - Новый приоритет: "none", "low", "medium", "high"
  • sortOrder (опционально) - Новый порядок сортировки
  • items (опционально) - Подзадачи для обновления:
    • id (обязательно) - ID подзадачи (обязательно для обновления)
    • title (обязательно) - Название подзадачи
    • status (опционально, по умолчанию 0) - Статус подзадачи
    • isAllDay (опционально) - Подзадача на весь день
    • startDate (опционально) - Дата начала подзадачи
    • timeZone (опционально) - Временная зона подзадачи
    • sortOrder (опционально) - Порядок сортировки подзадачи

complete_task

Отметить задачу как выполненную

• Параметры:
  • projectId (обязательно) - ID проекта
  • taskId (обязательно) - ID задачи

delete_task

Удалить задачу из TickTick

• Параметры:
  • projectId (обязательно) - ID проекта
  • taskId (обязательно) - ID задачи

get_all_projects_with_tasks

Получить все проекты пользователя вместе со всеми задачами в каждом проекте

• Параметры: Нет параметров

Доступные MCP ресурсы

📊 Статистика

ticktick://stats

Общая статистика по проектам и задачам

• Возвращает: JSON с общей статистикой (количество проектов, задач, выполненных, просроченных) и детальной статистикой по каждому проекту
• Включает: URI ресурса и временную метку

Примечание: Все инструменты используют токен доступа из переменной окружения TICKTICK_ACCESS_TOKEN.

Примеры запросов для Claude

Вот несколько примеров запросов для использования с Claude после подключения TickTick MCP сервера:

Базовые операции

• "Покажи мне все мои проекты TickTick"
• "Создай новую задачу 'Закончить документацию MCP сервера' в моем рабочем проекте с высоким приоритетом"
• "Покажи все задачи в моем личном проекте"
• "Отметь задачу 'Купить продукты' как выполненную"
• "Создай новый проект 'Планирование отпуска' с синим цветом"
• "Когда мой следующий дедлайн в TickTick?"

Продвинутые сценарии

• "Создай план на завтра: утром проверить почту, в 10:00 встреча с командой, в 14:00 работа над проектом"
• "Покажи статус всех моих проектов и количество незавершенных задач в каждом"
• "Создай проект для планирования мероприятия со всеми необходимыми задачами"
• "Какие задачи просрочены и требуют внимания?"

Приоритеты задач

Используйте строковые значения:

• "none" - Без приоритета (0)
• "low" - Низкий приоритет (1)
• "medium" - Средний приоритет (3)
• "high" - Высокий приоритет (5)

Форматы дат

Все даты должны быть в формате ISO 8601:

2024-12-31T23:59:59Z

Получение нового токена

Если ваш токен истек, просто запустите:

npm run get-token

Скрипт поднимет локальный сервер на порту 8080, откроет браузер для авторизации и автоматически получит новый токен.

Сервер обрабатывает обновление токенов автоматически, поэтому вам не нужно будет повторно аутентифицироваться, если вы не отзовете доступ или не удалите файл .env.

Разработка

Структура проекта

ticktick-mcp-ts/
├── src/
│   ├── client/
│   │   └── ticktick-client.ts    # Клиент для TickTick API с валидацией и retry логикой
│   ├── server/
│   │   └── ticktick-mcp-server.ts # MCP сервер с полным набором инструментов
│   ├── types/
│   │   └── ticktick.ts           # TypeScript типы и улучшенная обработка ошибок
│   ├── utils/
│   │   └── validators.ts         # Валидаторы для данных TickTick API
│   └── index.ts                  # Точка входа
├── get-token.ts                  # Скрипт для получения токена
├── test-server.ts                # Тест сервера
├── claude-desktop-config.json    # Пример конфигурации Claude
├── Dockerfile                    # Docker образ для контейнеризации
├── docker-compose.yml            # Docker Compose конфигурация
├── package.json
├── tsconfig.json
└── README.md

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

# Сборка
npm run build

# Запуск в режиме разработки
npm run dev

# Тестирование (с реальными API вызовами)
npm test

# Получение токена
npm run get-token

# Очистка
npm run clean

# Запуск сервера
npm start

Процесс аутентификации

Проект реализует полный OAuth 2.0 поток для TickTick:

1. Начальная настройка: Пользователь предоставляет свой TickTick API Client ID и Secret
2. Авторизация в браузере: Пользователь перенаправляется в TickTick для предоставления доступа
3. Получение токена: Локальный сервер получает OAuth callback с кодом авторизации
4. Обмен токена: Код обменивается на токены доступа и обновления
5. Хранение токена: Токены безопасно сохраняются в локальном файле .env

Это упрощает пользовательский опыт, обрабатывая весь OAuth поток программно.

Безопасность

• Никогда не коммитьте файл .env в репозиторий
• Храните токены доступа в безопасном месте
• Регулярно обновляйте токены доступа при необходимости
• Используйте переменные окружения для передачи токенов в продакшене

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

Ошибки токена

# Если токен истек или недействителен
npm run get-token

Проблемы с подключением

# Проверьте конфигурацию
npm test

Проблемы с портом

Если порт 8080 занят, скрипт получения токена может не работать. Убедитесь, что порт свободен или измените его в get-token.ts.

---

🚀 Рекомендуем: polza.ai - Российский агрегатор API нейросетей

Недавно нашёл для себя очень годный инструмент — российский сервис, который открывает API-доступ сразу к сотням нейросетей. Никаких VPN, никаких зарубежных карт — всё работает прямо из России! 🇷🇺

💡 Почему polza.ai?

Для интеграторов и разработчиков:

• 🔌 Простое подключение — понятная документация, быстрая интеграция
• 🛠️ Совместимость с популярными инструментами — n8n, Make, Zapier и другие
• 💰 Выгодные тарифы — реально экономичные цены на API вызовы
• 🏦 Российская платёжная система — работа с расчётного счёта, оплата в рублях

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

Уже протестировал в нескольких автоматизациях:

• 📱 Генерация контента для соцсетей — автоматические посты и описания
• 🤖 Telegram-боты с ИИ — умные ответы и обработка запросов
• 📧 Обработка заявок с сайта — автоматическая классификация и ответы
• 📬 Email-рассылки — персонализированные письма на основе ИИ

🔥 Что доступно

• GPT-подобные модели для генерации текста
• Классификация и анализ контента
• Перевод на множество языков
• Анализ кода и техническая документация
• Скоро: генерация изображений и видео! 🎨

👥 Для кого это особенно актуально

Если вы:

• 🔧 Интегратор или фрилансер — строите решения для клиентов
• 📈 Маркетолог — автоматизируете контент-процессы
• 🏢 Развиваете автоматизацию продаж под ключ
• 💻 Разработчик — внедряете ИИ в проекты

То polza.ai — это то, что вам нужно!

🎉 Начните прямо сейчас

Если вы давно хотели внедрять нейросети в проекты, но вас останавливали VPN, карты и сложные подключения — теперь всё решаемо.

🔗 Перейти на polza.ai →

Сервис полностью российский, удобный, выгодный и работает стабильно. Регистрируйтесь, тестируйте и начинайте строить свои AI-решения уже сейчас!

---

Содействие

Вклады приветствуются! Пожалуйста, не стесняйтесь отправлять Pull Request.

1. Форкните репозиторий
2. Создайте ветку для вашей функции (git checkout -b feature/amazing-feature)
3. Зафиксируйте ваши изменения (git commit -m 'Add some amazing feature')
4. Отправьте в ветку (git push origin feature/amazing-feature)
5. Откройте Pull Request

Лицензия

Этот проект лицензирован под MIT License

Поддержка

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