K Tick MCP

tick mcp

  

TickTick的MCP服务器 --通过以下方式管理任务、项目、习惯、标签、焦点统计数据等 模型上下文协议.

71工具 通过MCP公开，涵盖官方TickTick Open API（V1）和非官方网站API（V2）尚未公开的功能。

______________________________________________________________________

特性

查询/搜索亮点

• 结构化任务过滤 --文件夹、项目、标签、父/子任务形状、提醒、重复、检查表存在和优先级。
• 具有时间意识的议程访问 --按日期范围、日期时间范围和HH:MM时间窗口进行查询，而不强制先进行完全同步。
• Grep式匹配 --子字符串搜索， any / all / phrase 所选字段中的关键字模式、正则表达式和排除正则表达式。
• 有针对性的笔记搜索 --注释仅从范围内的NOTE项目中提取，而不是将整个工作区具体化。
• 工作区导航 --带有可选活动任务计数的文件夹/项目映射，用于在操作前检查帐户结构。
• 现成的操作视图 --基于同一过滤引擎构建的日视图、周窗口、即将到期的任务、过期/过时检测和优先级摘要。
• 已保存的查询预设 --持久化可重用的任务/笔记/议程/历史/周概览查询，并在以后执行它们，而无需重建过滤器集。

已验证的工作流助手

• 子任务安全创建 — create_subtask 创建子项，链接它，然后验证 parentId 和 childIds.
• 移动验证 — verified_move_tasks 重新读取目标项目，并确认每个移动的任务实际上都在那里。
• 文件夹分配验证 — verified_assign_project_folder 验证持久化 groupId 通过V2同步而不是通过误导性的V1响应。

意图优先发现

ticktick_guide() 支持技术类别和实际用户目标。

• 面向类别：

- ticktick_guide(category="tasks")

• 以意图为导向：

- ticktick_guide(intent="know_what_to_do_today") - ticktick_guide(intent="plan_the_week") - ticktick_guide(intent="find_a_note") - ticktick_guide(intent="reorganize_projects") - ticktick_guide(intent="clean_up_tasks")

包布局

src/tick_mcp/
├── mcp_api/
│   ├── core.py          # shared FastMCP instance, catalog, helpers
│   ├── utilities.py     # discovery + helper tools
│   ├── projects.py      # project CRUD tools
│   ├── tasks_read.py    # inbox / project / task reads
│   ├── tasks_write.py   # task mutation tools
│   ├── tasks_batch.py   # batch + structural task operations
│   ├── read.py          # high-level query/search, views, and saved presets
│   ├── verified.py      # safe wrappers with read-back verification + rollback hints
│   ├── folders.py       # folders + kanban columns
│   ├── tags.py          # tag tools
│   ├── habits.py        # habit tools
│   ├── history.py       # completed / deleted history
│   └── stats.py         # focus and user/productivity stats
├── services/
│   └── query.py         # reusable filtering, range and grep-like planning
├── client_api/
│   ├── transport.py     # auth, sessions, low-level V1/V2 HTTP helpers
│   ├── projects.py      # projects, folders, columns, tags
│   ├── tasks.py         # tasks, sync, batch, history
│   ├── habits.py        # habits and check-ins
│   └── stats.py         # focus and user/productivity stats
├── client.py            # stable public facade over client_api/*
├── models.py            # pydantic contracts
├── server.py            # stable public import surface for the MCP server
└── main.py              # CLI entrypoint

安装

# recommended — installs as a standalone tool
uv tool install tick-mcp

# or via pip
pip install tick-mcp

这提供了两个命令：

配置

1.环境变量

复制示例文件并填写您的令牌：

cp src/tick_mcp/.env.example src/tick_mcp/.env

获取V1令牌（最简单）：

1. 打开TickTick→ 设置→ 集成→ API
2. 复制显示的个人访问令牌

获取V2会话令牌：

1. 登录到 ticktick.com 在浏览器中
2. 开发者工具→ 应用→ Cookie→ 复制 t cookie值

或者使用CLI自动登录：

tick-admin session refresh

2.服务器配置

运行时设置已上线 src/tick_mcp/config.yaml -API端点、超时和用户年龄都是外部化的。

MCP客户端集成

克劳德桌面版

添加 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 ~/.config/Claude/claude_desktop_config.json （Linux）：

{
  "mcpServers": {
    "ticktick": {
      "command": "tick-mcp",
      "env": {
        "TICKTICK_API_TOKEN": "your-v1-token",
        "TICKTICK_SESSION_TOKEN": "your-v2-token"
      }
    }
  }
}

VS代码（GitHub副本）

添加 .vscode/mcp.json:

{
  "servers": {
    "ticktick": {
      "command": "tick-mcp",
      "env": {
        "TICKTICK_API_TOKEN": "your-v1-token",
        "TICKTICK_SESSION_TOKEN": "your-v2-token"
      }
    }
  }
}

其他MCP客户端

任何支持stdio传输的客户端都可以启动 tick-mcp 作为一个子流程。

发展

# Clone & install dev deps
git clone https://github.com/kpihx/tick-mcp.git
cd tick-mcp
uv sync --group dev

# Unit tests (155 selected unit tests, no network)
uv run pytest

# Live tests against real TickTick API (requires tokens in .env)
uv run pytest -m live

测试套件

• 155个选定的单元测试 --纯逻辑、模拟HTTP、零网络
• 12个实时集成脚本 -508针对真实TickTick API的断言

许可证

麻省理工学院 ©2025 Ivann KAMDEM