Ticktick MCP Ratv

TickTick MCP服务器

一 主控程序 服务器，让您的AI助手管理您的 TickTick 通过自然语言完成任务、项目、习惯等。适用于 克劳德代码, 光标, VS代码, 克劳德桌面，以及任何兼容MCP的客户端。

还支持 Dida365 （TickTick的中文版本）。

______________________________________________________________________

特性

44工具 跨越两个API层：

第1版 =官方TickTick Open API（OAuth2）。 第2版 =不在公共API中的功能的内部API（会话身份验证）。

______________________________________________________________________

设置

1.创建TickTick开发者应用程序

1. 首选 developer.ticktick.com/manager
2. 点击 +创建应用程序
3. 集 重定向URI 致： http://localhost:42813/callback
4. 注意你的 客户端ID 和 客户端密钥

2.安装并验证

git clone https://github.com/chrisvanek/ticktick-mcp-ratv.git
cd ticktick-mcp-ratv
npm install && npm run build

# Run the interactive setup wizard
node build/index.js auth

向导将指导您完成以下操作：

1. TickTick登录 （电子邮件+密码）--启用V2功能（标签、习惯、焦点、已完成的任务）
2. OAuth2流 （客户端ID+密码+浏览器身份验证）-启用V1功能（项目、任务）

凭据保存到本地 .env 文件（从git中排除）。

3.连接到您的AI客户端

将服务器添加到MCP客户端配置中。用您的凭据替换占位符值 .env 文件。

Claude Code

CLI（推荐）：

claude mcp add ticktick-mcp-server \
  node /absolute/path/to/ticktick-mcp-ratv/build/index.js \
  -e TICKTICK_CLIENT_ID=your_client_id \
  -e TICKTICK_CLIENT_SECRET=your_client_secret \
  -e TICKTICK_ACCESS_TOKEN=your_access_token \
  -e TICKTICK_REFRESH_TOKEN=your_refresh_token \
  -e TICKTICK_USERNAME=your_email \
  -e TICKTICK_PASSWORD=your_password \
  -s user

使用 -s user （随处可见）， -s project （与团队共享），或 -s local （单个项目）。

配置文件 (~/.claude.json 或 .mcp.json):

{
  "mcpServers": {
    "ticktick": {
      "command": "node",
      "args": ["/absolute/path/to/ticktick-mcp-ratv/build/index.js"],
      "env": {
        "TICKTICK_CLIENT_ID": "your_client_id",
        "TICKTICK_CLIENT_SECRET": "your_client_secret",
        "TICKTICK_ACCESS_TOKEN": "your_access_token",
        "TICKTICK_REFRESH_TOKEN": "your_refresh_token",
        "TICKTICK_USERNAME": "your_email",
        "TICKTICK_PASSWORD": "your_password"
      }
    }
  }
}

验证 /mcp 克劳德密码。

Cursor

创建或编辑 ~/.cursor/mcp.json （全球）或 .cursor/mcp.json （项目）：

{
  "mcpServers": {
    "ticktick": {
      "command": "node",
      "args": ["/absolute/path/to/ticktick-mcp-ratv/build/index.js"],
      "env": {
        "TICKTICK_CLIENT_ID": "your_client_id",
        "TICKTICK_CLIENT_SECRET": "your_client_secret",
        "TICKTICK_ACCESS_TOKEN": "your_access_token",
        "TICKTICK_REFRESH_TOKEN": "your_refresh_token",
        "TICKTICK_USERNAME": "your_email",
        "TICKTICK_PASSWORD": "your_password"
      }
    }
  }
}

保存后重新启动Cursor。

VS Code (Copilot Agent Mode)

需要使用GitHub Copilot的VS代码1.99+。创建 .vscode/mcp.json:

{
  "servers": {
    "ticktick": {
      "command": "node",
      "args": ["/absolute/path/to/ticktick-mcp-ratv/build/index.js"],
      "env": {
        "TICKTICK_CLIENT_ID": "your_client_id",
        "TICKTICK_CLIENT_SECRET": "your_client_secret",
        "TICKTICK_ACCESS_TOKEN": "your_access_token",
        "TICKTICK_REFRESH_TOKEN": "your_refresh_token",
        "TICKTICK_USERNAME": "your_email",
        "TICKTICK_PASSWORD": "your_password"
      }
    }
  }
}

Claude Desktop

编辑配置文件：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %AppData%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ticktick": {
      "command": "node",
      "args": ["/absolute/path/to/ticktick-mcp-ratv/build/index.js"],
      "env": {
        "TICKTICK_CLIENT_ID": "your_client_id",
        "TICKTICK_CLIENT_SECRET": "your_client_secret",
        "TICKTICK_ACCESS_TOKEN": "your_access_token",
        "TICKTICK_REFRESH_TOKEN": "your_refresh_token",
        "TICKTICK_USERNAME": "your_email",
        "TICKTICK_PASSWORD": "your_password"
      }
    }
  }
}

退出并重新启动克劳德桌面（Cmd+Q/Alt+F4）。

Cline (VS Code extension)

打开Cline面板>MCP服务器图标>配置，然后添加：

{
  "mcpServers": {
    "ticktick": {
      "command": "node",
      "args": ["/absolute/path/to/ticktick-mcp-ratv/build/index.js"],
      "env": {
        "TICKTICK_CLIENT_ID": "your_client_id",
        "TICKTICK_CLIENT_SECRET": "your_client_secret",
        "TICKTICK_ACCESS_TOKEN": "your_access_token",
        "TICKTICK_REFRESH_TOKEN": "your_refresh_token",
        "TICKTICK_USERNAME": "your_email",
        "TICKTICK_PASSWORD": "your_password"
      }
    }
  }
}

Dida365（中国）

添加 TICKTICK_HOST=dida365 您的环境变量。这将API调用路由到 api.dida365.com.

节点版本管理器（nvm、fnm等）

如果 node 在MCP客户端中无法解析，请使用完整路径：

"command": "/Users/you/.nvm/versions/node/v22.0.0/bin/node"

______________________________________________________________________

用法示例

一旦连接，就自然地说话。以下是根据您的能力组织的示例：

晨间计划

“给我每日总结”

“什么逾期了？”

“我这周要交什么？”

“显示所有高优先级任务”

创建任务

“在我的工作项目中创建一个名为“审查PR#42”的任务，明天到期，优先级高”

将“购买杂货”任务添加到“个人”中，其中包含子任务：牛奶、鸡蛋、面包、黄油

“每周一在我的工作项目中创建一个定期任务‘每周站立笔记’”

“在我的工作项目中创建这些任务：查看设计模型，更新API文档，修复登录错误”

管理任务

“将“发送发票”任务标记为已完成”

“将‘设计审查’移至我的工作项目”

“将‘编写测试’作为‘Ship v2’的子任务”

“我上周完成了哪些任务？”

搜索和筛选

“搜索任何提及‘预算’的任务”

“显示所有中等优先级任务”

“未来3天有哪些任务要完成？”

“显示我的个人项目中有截止日期的所有任务”

项目

“列出我的所有项目”

“使用看板视图创建一个名为“Q2目标”的新项目”

“显示我的工作项目中的所有内容——任务、列、工作”

标签

“显示我的所有标签”

“创建一个名为‘紧急’的红色标签”

“将'bug'标记重命名为'bugfix'”

“将‘todo’标签合并到‘backlog’中”

习惯

“我有什么习惯？”

“检查我今天的‘喝水’习惯”

“养成一种叫做‘阅读’的习惯，目标是每天阅读30页”

“显示我自1月以来的所有入住记录”

专注与生产力

“显示我本月的焦点时间热图”

“我的注意力时间在标签之间是如何分配的？”

“我的生产力统计数据是什么？”

组织

“列出我的项目文件夹”

“创建一个名为“侧项目”的文件夹”

“在我的Sprint项目中显示看板列”

“我的垃圾桶里有什么？”

______________________________________________________________________

环境变量

安全说明： V2 API需要您的TickTick用户名和密码。这些作为环境变量存储，除了直接传输到TickTick的身份验证端点外，从不记录或传输到任何地方。这 .env 文件是使用受限权限（仅限所有者读/写）创建的。

______________________________________________________________________

全部44个工具

Project Management (6 tools, V1)

Task Management (6 tools, V1)

Smart Queries & GTD (13 tools, V1)

Tags (5 tools, V2)

Habits (6 tools, V2)

Focus / Pomodoro (3 tools, V2)

Completed & Trashed Tasks (2 tools, V2)

Task Organization (2 tools, V2)

Kanban & Folders (6 tools, V2)

User & Settings (2 tools, V2)

______________________________________________________________________

参考

任务优先级值： 0 =无， 1 =低， 3 =中等， 5 =高

日期格式： yyyy-MM-dd'T'HH:mm:ssZ （例如。 2025-03-15T09:00:00+0000)

重复规则： 标准RRULE格式（例如。 RRULE:FREQ=DAILY;INTERVAL=1)

______________________________________________________________________

发展

npm install       # Install dependencies
npm run build     # Compile TypeScript
npm run dev       # Watch mode
npm run clean     # Remove build output

添加工具

1. 将您的工具添加到相应的文件中 src/tools/
2. 使用 server.registerTool() 使用Zod输入模式
3. 它自动对所有MCP客户端可用

建筑

src/
├── index.ts              # Entry point + auth CLI routing
├── config.ts             # Environment variable loader
├── client.ts             # V1 API client (OAuth2)
├── client-v2.ts          # V2 API client (session auth)
├── types.ts              # TypeScript interfaces
├── auth-cli.ts           # Interactive auth wizard
├── auth/oauth.ts         # OAuth2 flow implementation
└── tools/
    ├── project-tools.ts  # Project CRUD (V1)
    ├── task-tools.ts     # Task CRUD (V1)
    ├── smart-tools.ts    # Smart queries & GTD (V1)
    ├── tag-tools.ts      # Tag management (V2)
    ├── habit-tools.ts    # Habit tracking (V2)
    ├── focus-tools.ts    # Focus/Pomodoro stats (V2)
    ├── column-tools.ts   # Kanban columns (V2)
    ├── folder-tools.ts   # Project folders (V2)
    └── v2-task-tools.ts  # Completed tasks, move, user (V2)

两个API客户端都透明地处理身份验证-过期令牌将在401个响应上自动刷新。

______________________________________________________________________

故障排除

______________________________________________________________________

贡献

1. 分叉回购
2. 创建要素分支
3. 进行更改并运行 npm run build
4. 打开拉取请求

______________________________________________________________________

许可证

麻省理工学院——见 许可证.

致谢

• TickTick开放API
• 模型上下文协议