AI导哈

任务管理CLI工具

一个通过CLI和MCP服务器与TickTick任务管理服务交互的工具，支持AI代理读取和修改项目和任务。

  • by echomodel
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 krisrowe/ticktick-mcp

使用说明

ticktick访问

CLI和MCP服务器 TickTick 任务管理。 将TickTick Open API包装为MCP工具，因此AI代理（Claude Code， Gemini CLI、Claude.ai和任何MCP客户端）都可以读取和修改您的 项目和任务。

该软件包安装了三个命令：

  • ticktick-mcp --MCP服务器（HTTP和stdio传输）
  • ticktick-admin --用户和部署管理
  • ticktick --获取TickTick访问令牌的小型OAuth助手

MCP服务器通过stdio在本地运行供个人使用，或通过HTTP运行 用于多用户共享部署。每用户TickTick代币存在 用户存储，从不在共享配置文件或环境变量中。

建立在 mcp应用程序.

安装

需要Python 3.11+和 pipx.

pipx install git+https://github.com/echomodel/ticktick-mcp.git

这将安装 ticktick, ticktick-mcp，以及 ticktick-admin 在你的 PATH.

TickTick OAuth凭据（一次性）

每个用户都需要一个TickTick访问令牌。要获得一个：

  1. 在以下网址注册应用程序 developer.ticktic.com.

  2. 将OAuth重定向URI设置为 http://localhost:8080.

  3. 注意 客户端ID 和 客户端密钥.

  4. 运行OAuth帮助程序：

    ticktick auth login \
    --client-id <client-id> \
    --client-secret <client-secret>

    或者，为了在命令行中隐藏秘密：

    export TICKTICK_CLIENT_ID=<client-id>
export TICKTICK_CLIENT_SECRET=<client-secret>
ticktick auth login

    浏览器打开，您授权应用程序和访问令牌 打印到stdout。TickTick代币目前大约在以下时间到期 24小时，因此当令牌到期时，您将重复此操作。

然后，令牌将进入本地用户记录（用于stdio模式） 或者部署的用户记录（用于HTTP模式）——见下文。

在本地运行（stdio）

供个人在一台机器上使用。

1.配置本地模式并注册本地用户

ticktick-admin connect local
ticktick-admin users add local --access-token <ticktick-token>

connect local 写 ~/.config/ticktick/setup.json 因此，后续 ticktick-admin 命令以本地用户存储为目标。 users add local 写入用户记录（带有TickTick令牌） 配置文件）下 $XDG_DATA_HOME/ticktick/users/.

当TickTick代币到期时，无需重新注册即可轮换：

ticktick-admin users update-profile local access_token <new-token>

2.在客户端注册MCP服务器

克劳德代码：

claude mcp add ticktick -- ticktick-mcp stdio --user local

Gemini CLI：

gemini mcp add ticktick --command ticktick-mcp --args "stdio --user local"

这 --user local 标志告诉MCP服务器要记录哪个用户 在stdio上运行时加载。

3.烟雾测试

在您的MCP客户端中，要求代理列出您的TickTick项目。 服务器通过以下方式返回项目ID、名称和元数据 list_projects 工具。

部署（HTTP）

用于共享、多用户、始终在线的访问——通常用于web 客户喜欢 Claude.ai 和远程代理 部署。

运行时合同

任何HTTP部署都必须提供：

变量 必填 默认 用途
SIGNING_KEY 是 --启动失败 用于签名JWT的HMAC密钥（32+随机字符）
APP_USERS_PATH 是的，坚持 ~/.local/share/ticktick/users/ 保存每个用户JSON记录的目录（必须是持久存储）
JWT_AUD 否 未设置 预期JWT aud 索赔。如果未设置，则不会验证受众
TOKEN_DURATION_SECONDS 否 ~10年 新发行用户代币的有效期
LOG_LEVEL 没有 INFO 标准Python日志级别

服务器：

  • 继续收听 0.0.0.0:8080 （用覆盖 --host / --port)
  • 为MCP传输提供服务 /
  • 服务于 GET /health 端点（无身份验证）返回 {"status":"ok"}
  • 服务 /admin/users, /admin/tokens, /admin/users/{email}/profile （通过JWT认证，签名为 SIGNING_KEY, scope=admin)
  • 处理自己的身份验证——平台必须允许未经身份验证的HTTP 通过应用程序

启动命令（任何进程监控器，包括Dockerfile CMD):

ticktick-mcp serve --host 0.0.0.0 --port 8080

码头工人

此仓库中附带了基线Dockerfile。要构建和运行：

docker build -t ticktick-access .
docker run -p 8080:8080 \
    -e SIGNING_KEY="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')" \
    -v $(pwd)/.users:/data/users \
    -e APP_USERS_PATH=/data/users \
    ticktick-access

同样的镜像可以在Python容器运行的任何地方运行——Cloud Run， Fly、Render、Heroku（通过Buildpack）、Railway、Kubernetes、ECS、， 裸金属。

gapp（云运行）

如果你使用 gapp, gapp.yaml 描述了具有托管功能的Cloud Run部署 SIGNING_KEY 和 APP_USERS_PATH.使用以下方式部署：

gapp deploy

gapp生成和存储 SIGNING_KEY 在秘密经理第一 为部署和配置持久卷 APP_USERS_PATH.

这是许多受支持的路径之一——上面的运行时契约 这才是最重要的；gapp很方便。

将管理员CLI连接到已部署的实例

在部署之后， ticktick-admin 需要部署URL和 SIGNING_KEY 管理用户的价值。

ticktick-admin connect https://your-ticktick-mcp.example.com \
    --signing-key <signing-key>

检索 <signing-key> 无论部署存储在何处：

  • gapp: gapp_secret_get(name="signing-key", plaintext=True) 通过 间隙MCP，或 gcloud secrets versions access latest --secret=ticktick-mcp-signing-key.
  • GCP秘密经理直接: gcloud secrets versions access latest --secret=<your-secret-name>.
  • GitHub操作/CI秘密：从CI提供商的UI读取。
  • 其他秘密管理者：使用该工具的read命令。

connect 将URL和签名密钥保存到 ~/.config/ticktick/setup.json 因此，后续的管理命令将运行 而不重复旗帜。随时切换回本地 ticktick-admin connect local.

管理已部署实例上的用户

# Register a new user. Their TickTick token goes in the profile.
ticktick-admin users add alice@example.com --access-token <token>

# List registered users.
ticktick-admin users list

# Read the current profile (which fields are set, which are missing).
ticktick-admin users get-profile alice@example.com

# Rotate a user's TickTick token after the old one expires.
ticktick-admin users update-profile alice@example.com access_token <new-token>

# Mint an additional MCP-server token for an existing user
# (e.g. to register the MCP server in another client).
ticktick-admin tokens create alice@example.com

# Revoke a user.
ticktick-admin users revoke alice@example.com

跑 ticktick-admin users add --help 查看键入的标志 生成自 Profile 模型-- --access-token 旗帜的帮助 文本描述了令牌是什么以及如何获得令牌。

验证并注册MCP客户端

探测部署

ticktick-admin probe

probe 检查 /health，然后打开MCP会话和往返 工具列表。输出每个注册工具的名称-- list_projects, count_projects, list_tasks, create_task, update_task, complete_task, delete_task。如果部署正常，并且 工具暴露， probe 报告 MCP: ok.

添加 --json 用于适合脚本和代理的结构化输出。

检查正在运行的部署上的工具

如果 probe 报告问题或您想更仔细地了解 部署正在公开 tools 组对以下对象调用JSON-RPC 活MCP传输：

ticktick-admin tools list                       # enumerate tool names
ticktick-admin tools show list_projects         # show schema and example
ticktick-admin tools call list_projects         # invoke with no args
ticktick-admin tools call create_task --arg project_id=<id> --arg title='Hello'

tools call 生成一个短期用户范围的令牌（默认值：first 注册用户；用以下方式覆盖 --user <email>)往返 通过部署的MCP层，就像MCP客户端一样。

端到端烟雾测试

ticktick-admin safe-tool --invoke

援引 count_projects 通过部署的MCP实现端到端 传输——从JWT验证到工具调度的完整路径 到TickTick的API并返回。答案只是一个计数，所以 练习整个堆栈，而不显示任何用户编写的内容 在管理输出中。

生成MCP客户端注册命令

ticktick-admin register --user alice@example.com

铸造一个新的用户范围令牌，并发出可粘贴的注册 用于Claude Code、Gemini CLI和Claude.ai URL表单的命令， 每个预填充有部署URL和新令牌。添加 --json 用于适合脚本和代理的结构化输出。

仅限于特定客户：

ticktick-admin register --user alice@example.com --client claude
ticktick-admin register --user alice@example.com --client gemini
ticktick-admin register --user alice@example.com --client claude.ai

手动MCP客户端注册

如果你不想使用 register，这些模式是：

克劳德代码：

claude mcp add --scope user ticktick \
    --transport http \
    --url https://your-deployment/ \
    --header "Authorization: Bearer ${TICKTICK_TOKEN}"

Gemini CLI：

gemini mcp add ticktick \
    --transport http \
    --url https://your-deployment/ \
    --header "Authorization: Bearer ${TICKTICK_TOKEN}"

两个客户都在扩张 ${VAR} 在headers中，请将令牌放入您的 shell环境，而不是注册命令。

MCP工具暴露

工具 说明
list_projects 列出所有TickTick项目（列表）
count_projects 返回项目数量（安全烟雾测试工具——见下文）
list_tasks 列出项目中的任务
create_task 创建新任务
update_task 更新现有任务
complete_task 将任务标记为已完成
delete_task 永久删除任务

故障排除

TickTick的“No TickTick访问令牌”/401 --用户的 令牌已过期。跑 ticktick auth login那么 ticktick-admin users update-profile <email> access_token <new>.

部署上“找不到用户” --使用以下方式注册用户 ticktick-admin users add.

MCP客户端无法从您的部署连接/401/403 — 用户范围的MCP令牌已过期或被吊销。铸造新的 一用 ticktick-admin tokens create <email> 并更新 客户的注册。

管理命令失败，显示“未配置” --奔跑 ticktick-admin connect local 或 ticktick-admin connect <url> --signing-key <key>.

测试

单元测试在没有凭据的情况下脱机运行：

make test            # creates venv on first run, then runs all tests

这 tests/framework/ 目录包含mcp应用程序的可重用性 一致性套件——身份验证实施、管理端点、JWT处理、， CLI布线、工具协议、SDK覆盖率。直接用以下命令运行：

make framework-test

进一步阅读

  • 贡献.md --架构、添加工具， 配置文件字段、测试标准。
  • mcp应用程序 --框架 这个应用程序是基于构建的。

许可证

麻省理工学院

相关 MCP