Ticktick Api Mcp (typescript)

TickTick MCP 服务器（TypeScript）

使用 TypeScript 编写的服务器，用于集成 TickTick API，采用 Model Context Protocol (MCP)。

🚀 顺便说一句！ 如果你正在使用 AI 和自动化，不妨关注 polza.ai——俄罗斯的神经网络 API 聚合平台。无需 VPN，可使用俄罗斯银行卡付款，并支持与 n8n/Make/Zapier 集成。非常适合你的 AI 项目！🇷🇺

功能

• 🔑 简单的身份验证 - 使用环境变量中的 access token
• 📋 项目管理 - 创建、查看和删除项目（包括支持 TASK 和 NOTE 类型）
• ✅ 任务管理 - 创建、更新、完成和删除任务
• 🛠️ 独立的令牌获取脚本 - 轻松获取 access token
• 📊 配置信息 - 通过资源查看当前设置
• 🔌 与 Claude 和其他 MCP 客户端无缝集成
• 🐳 Docker 支持 - 在容器中运行并通过 HTTP 访问
• ✅ 可靠的验证 - 自动检查并转换数据
• 🔄 重试逻辑 - 临时错误发生时自动重试
• 📝 详细日志记录 - 提供详细日志以便调试

前置条件

• Node.js 18 或更高版本
• npm 或 yarn
• TickTick API 凭据（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.example 创建 .env 文件：

# 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

连接后，你会在 Claude 中看到 TickTick MCP 服务器提供的工具，并以 🔨（工具）图标标示。

🐳 在 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
   

通过 HTTP 与 Claude 搭配使用

容器启动后，MCP 服务器将在端口 8002 上通过 HTTP 提供访问。将以下配置添加到 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	MCP 服务的 HTTP 访问端口	8002
TICKTICK_ACCESS_TOKEN	TickTick API 的访问令牌	必填
TICKTICK_BASE_URL	TickTick API 的基础 URL	https://api.ticktick.com/open/v1
TICKTICK_CLIENT_ID	客户端 ID（仅用于获取令牌）	-
TICKTICK_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

身份验证流程

项目为 TickTick 实现了完整的 OAuth 2.0 流程：

1. 初始设置：用户提供自己的 TickTick API Client ID 和 Secret
2. 浏览器授权：用户将被重定向到 TickTick 以授予访问权限
3. 获取令牌：本地服务器接收包含授权码的 OAuth 回调
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 调用价格真正经济划算
• 🏦 俄罗斯支付系统——可使用结算账户，支持卢布付款

🎯 使用示例

我已经在几项自动化任务中测试过：

• 📱 社交媒体内容生成——自动生成帖子和描述
• 🤖 带 AI 的 Telegram 机器人——智能回复和请求处理
• 📧 网站请求处理——自动分类并回复
• 📬 电子邮件群发——基于 AI 的个性化邮件

🔥 可用功能

• 用于文本生成的 GPT 类模型
• 内容分类与分析
• 翻译成多种语言
• 代码分析和技术文档
• 即将推出：图像和视频生成！🎨

👥 特别适合哪些人

如果你是：

• 🔧 集成商或自由职业者——为客户构建解决方案
• 📈 营销人员——自动化内容工作流
• 🏢 销售自动化服务提供者——提供端到端解决方案
• 💻 开发者——在项目中集成 AI

那么 polza.ai 正是你需要的！

🎉 立即开始

如果你一直想在项目中集成神经网络，却受 VPN、银行卡和复杂接入流程所阻碍，现在这些问题都能解决。

🔗 前往 polza.ai →

这是一项完全俄罗斯本土的服务，方便、实惠且运行稳定。立即注册、测试并开始构建自己的 AI 解决方案！

---

贡献

欢迎贡献！请随时提交 Pull Request。

1. Fork 此代码库
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。