使用说明

TickTick MCP服务器

一种用于TickTick任务管理的综合模型上下文协议（MCP）服务器 API覆盖率100% （112次操作）。

🎉 突破：任务缓存系统

新解决了用户无法列出任务的主要用户体验问题。现在你可以简单地说：

“给我所有任务” ✅
“列出项目X中的任务” ✅
“显示我的缓存任务” ✅

🚀 缓存功能

自动注册：新任务自动缓存
24小时TTL：新鲜与陈旧任务检测
CSV导入：带有现有数据的Bootstrap
即时发现：批量API不再出现500个错误
本地存储: ~/.ticktick-mcp-cache.json

# Now this works perfectly!
ticktick_get_cached_tasks()           # List all cached tasks
ticktick_register_task_id()           # Add existing tasks  
ticktick_import_from_csv()            # Bulk import
# All new tasks auto-cached ✨

🤖 使用Claude Code创建

此项目是使用创建的克劳德代码 -Anthropic为克劳德提供的官方CLI。专为希望在开发工作流程中无缝集成TickTick的Claude Code用户而构建。

✨ 特性

完成TickTick API覆盖（112次运营）

核心任务管理（24次操作）

✅ 创建、读取、更新、删除任务
✅ 任务完成和状态管理
✅ 截止日期、优先事项和提醒
✅ 任务搜索和筛选
✅ 批量任务操作

项目管理（36次操作）

✅ 项目创建和管理
✅ 高级项目操作（克隆、存档、收藏夹）
✅ 项目模板和智能列表
✅ 团队协作与分享
✅ 权限管理和成员邀请

高级功能（52次操作）

✅ 习惯与追踪：习惯创建、签到、条纹、分析
✅ 聚焦时间：番茄工作时间、时间跟踪、生产力指标
✅ 标签和标签：高级标记、自定义标签、组织
✅ 日历集成：事件同步、日历管理、日程安排
✅ 注释和附件：富格文本注释、文件附件、媒体
✅ 模板和自动化：任务模板、重复模式、自动化
✅ 分析和报告：生产力报告、目标跟踪、数据导出
✅ 设置和首选项：用户自定义、通知、同步设置

🚀 快速开始

先决条件

Node.js 18+
具有API访问权限的TickTick帐户
已安装Claude Code CLI

安装

克隆存储库

git clone https://github.com/YOUR_USERNAME/ticktick-mcp-server.git
cd ticktick-mcp-server

安装依赖项
```
npm install
```

设置环境变量

# Create .env file
TICKTICK_ACCESS_TOKEN=your_access_token_here
TICKTICK_CLIENT_ID=your_client_id_here
TICKTICK_CLIENT_SECRET=your_client_secret_here

启动服务器
```
npm start
```

Docker部署

# Build the image
docker build -t ticktick-mcp .

# Run the container
docker run -d \
  --name ticktick-mcp \
  -e TICKTICK_ACCESS_TOKEN=your_token \
  -p 8007:8007 \
  ticktick-mcp

🔧 使用Claude代码进行配置

添加到您的Claude Code MCP设置中：

{
  "mcpServers": {
    "ticktick": {
      "command": "node",
      "args": ["/path/to/ticktick-mcp/src/index.js"],
      "env": {
        "TICKTICK_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

📖 使用示例

🚀 新增：基于缓存的任务发现

// 🎉 The breakthrough feature - list all your tasks!
await ticktick_get_cached_tasks();
// Returns: All cached tasks with fresh/stale status

// Register existing tasks for discovery
await ticktick_register_task_id({
  task_id: "existing_task_123",
  project_id: "project_456", 
  title: "My Existing Task"
});

// Import tasks from CSV export
await ticktick_import_from_csv({
  csv_data: "task_id,project_id,title\ntask1,proj1,Design\ntask2,proj1,Development"
});

// Filter cached tasks by project
await ticktick_get_cached_tasks({ project_id: "specific_project" });

任务管理

// Create a new task (auto-cached! ✨)
await ticktick_create_task({
  title: "Review Claude Code documentation",
  project_id: "inbox",
  priority: 3,
  due_date: "2024-12-31"
});
// Task automatically appears in cache for easy discovery

// Get all projects
await ticktick_get_projects({ include_archived: false });

// Complete a task
await ticktick_complete_task({ task_id: "task123" });

高级功能

// Start a focus session
await ticktick_start_focus_session({
  duration: 25, // Pomodoro: 25 minutes
  task_id: "task123"
});

// Track habit completion
await ticktick_check_in_habit({
  habit_id: "habit456",
  date: "2024-01-15"
});

// Generate productivity report
await ticktick_get_productivity_report({
  period: "week",
  include_charts: true
});

🏗️ 建筑

基于模型上下文协议（MCP）规范构建：

运输：stdio（标准输入/输出）
认证：OAuth2承载令牌
错误处理：使用用户友好的消息进行全面的尝试捕获
响应格式：带有表情符号和结构化数据的丰富降价

⚠️ 关键：TickTick API同步限制

重要：TickTick有隐藏的同步限制，这些限制没有记录在其API中。我们的广泛测试揭示了关键问题：

🚫 破坏同步的角色

使用这些字符创建的任务将返回API成功（200），但是 不会出现在TickTick应用程序中:

// ❌ THESE BREAK SYNC (avoid in task content):
"content": "Line 1\nLine 2"           // Actual newlines
"content": "Path: C:\\Users\\folder"  // Backslashes  
"content": "Literal \\n in text"     // Escape sequences
"content": "Quote: \"hello\""        // Escaped quotes in content

✅ 完美工作的角色

// ✅ THESE ARE SAFE (work perfectly):
"content": "Emojis work: 💻🚀📊✅❌🔧🎯📁⚡🤖"     // All emojis
"content": "Arrows: → ← ↑ ↓ ↗ ↖ ↘ ↙"               // All arrows  
"content": "Bullets: • ○ ■ ▪ ▫ ◦ ‣"                // All bullets
"content": "Unicode: ñ é ü ç § ± © ® ™"             // All Unicode
"content": "JSON: { } [ ] and arrays [1,2,3]"      // JSON chars
"content": "Markdown: # header *bold* **strong**"   // Markdown
"content": "Quotes work fine in content"            // Regular quotes

🔧 工作工作流命令

创建任务（安全方法）

# ✅ WORKING - Basic task creation
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ticktick_create_task","arguments":{"title":"My Task","content":"Safe content without newlines or backslashes","project_id":"your_project_id"}}}' | node src/index.js

# ✅ WORKING - With emojis and arrows  
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ticktick_create_task","arguments":{"title":"💻 Coding Task","content":"Use arrows for workflow: Plan → Code → Test → Deploy 🚀","project_id":"your_project_id"}}}' | node src/index.js

测试您的设置

# Test if your token works
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ticktick_get_projects","arguments":{}}}' | node src/index.js

# Create a test task (should appear in your TickTick app)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ticktick_create_task","arguments":{"title":"API Test","content":"This task should appear in your TickTick app within seconds"}}}' | node src/index.js

✅ 突破：任务阅读现在有效！

主要更新：通过使用正确的端点模式修复了任务读取！

工作命令:

# Read specific task (requires both project_id and task_id)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ticktick_get_task_details","arguments":{"project_id":"YOUR_PROJECT_ID","task_id":"YOUR_TASK_ID"}}}' | node src/index.js

# 🎯 CRITICAL: Read inbox tasks (special project ID discovered!)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ticktick_get_task_details","arguments":{"project_id":"inbox125308274","task_id":"YOUR_TASK_ID"}}}' | node src/index.js

🔑 关键发现：收件箱具有特殊的项目ID inbox125308274 -在项目列表中不可见，但阅读收件箱任务时需要！

✅ API状态-完全工作！

任务创建: ✅ 完美工作（具有以下字符限制）
任务阅读: ✅ 确认工作 -固定端点模式在生产中工作
项目列表: ✅ 工作完美
任务管理: ✅ 完整的CRUD操作现在可以运行了
🎉 缓存系统: ✅ 新经过充分测试和工作 -完整的任务发现解决方案

🧪 验证和测试

缓存系统测试（100%通过率）

# Test cache functionality
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ticktick_get_cached_tasks","arguments":{}}}' | node src/index.js

# Test task registration  
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ticktick_register_task_id","arguments":{"task_id":"test123","project_id":"proj456","title":"Test Task"}}}' | node src/index.js

# Test CSV import
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ticktick_import_from_csv","arguments":{"csv_data":"task_id,project_id,title\ntask1,proj1,Test"}}}' | node src/index.js

API基本测试

# Test basic functionality
node validate-ticktick-mcp.js

# Test character compatibility (recommended before using)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ticktick_create_task","arguments":{"title":"Compatibility Test","content":"Testing safe characters: emojis 💻, arrows →, unicode é, bullets •"}}}' | node src/index.js

验证结果：

✅ 缓存系统：所有功能均正常工作（注册、持久化、自动缓存、CSV导入）
✅ 任务创建：完美地应对角色限制
✅ 任务阅读： 确认工作 -固定端点模式
✅ 项目管理：功能齐全
✅ 复杂操作：现在可以完全操作工作任务读取

🤝 贡献

这个项目是用Claude Code为Claude Code社区创建的。欢迎投稿！

分叉存储库
创建要素分支
进行更改
使用验证套件进行测试
提交拉取请求

📜 许可证

MIT许可证-请参阅许可证文件以获取详细信息。

🙏 致谢

Claude代码团队 -创造一个令人惊叹的人工智能开发环境
TickTick API -提供全面的任务管理功能
MCP规范 -实现无缝的AI工具集成
原创灵感 -基于 jen6/ticktick mcp

🔗 相关项目

内置于❤️ 使用克劳德代码

非常适合那些希望将TickTick集成到其Claude Code工作流中的开发人员，该工作流具有完整的API覆盖范围和全面的任务管理功能。