Tick Tick MCP Server

TickTick API客户端和MCP服务器

  

TickTick的Python客户端库 使用它的两种方法:

1. MCP服务器 -通过自然对话与Claude Desktop一起使用TickTick
2. Python命令行界面/库 -用于自动化和脚本编写的程序化访问

选择你的冒险

🤖 想在Claude Desktop上使用TickTick吗？

→ MCP服务器设置

通过对话管理任务：

You: "Add a high priority task to call mom tomorrow"
Claude: ✓ Created task: Call mom (Priority: High, Due: tomorrow)

💻 想要CLI工具还是Python自动化？

→ 继续阅读下面

使用命令行工具或构建自定义脚本：

python add_task.py "Buy groceries" --priority 5 --due today

______________________________________________________________________

概述

该项目提供了三种与TickTick交互的方法：

1. MCP服务器 (ticktick_mcp_server.py)Claude Desktop的模型上下文协议服务器
2. REST API客户端 (ticktick_rest_api.py)-用于自动化的直接REST API实现
3. OAuth客户端 (ticktick_setup.py)-使用 ticktick-py 图书馆（目前已损坏）

特性

MCP服务器：

• 自然语言任务创建和管理
• 通过Claude Desktop实现对话界面
• 实时任务状态和项目概述
• 任务和项目的模糊搜索

Python客户端：

• 创建和管理TickTick项目（列表）
• 使用RRULE语法创建重复任务
• 设置任务优先级、截止日期和提醒
• 带有令牌缓存的OAuth2身份验证
• 用于高级用例的REST API实现
• 用于快速添加任务的命令行工具

快速入门（5分钟）

1.安装依赖项

pip install -r requirements.txt

2.配置凭据

复制 .env.example 到 .env 并添加您的凭据：

cp .env.example .env

编辑 .env:

TICKTICK_USERNAME=your-email@example.com
TICKTICK_PASSWORD=your-password

对于REST API的使用，还要添加：

TICKTICK_CLIENT_ID=your-client-id-here
TICKTICK_CLIENT_SECRET=your-client-secret-here
TICKTICK_REDIRECT_URI=http://127.0.0.1:8080

获取API凭据：

1. 首选https://developer.ticktick.com/manage
2. 点击“+应用程序名称”并创建应用程序
3. 将重定向URI设置为： http://127.0.0.1:8080
4. 复制您的客户端ID和客户端密码

3.测试认证

# Test OAuth client
python test_ticktick_auth.py

# Or test REST API
python ticktick_rest_api.py

使用示例

快速入门：添加单个任务（推荐）

添加任务最简单的方法是使用 add_task.py 脚本：

# Simple task
python add_task.py "Buy groceries"

# Task with description
python add_task.py "Exercise" --content "30 min walk in the park"

# High priority task in a specific project
python add_task.py "Morning workout" --project Health --priority 5

# Task with due date
python add_task.py "Doctor appointment" --due "2025-11-20" --priority 5

# Task due today or tomorrow
python add_task.py "Call Nicole" --due today --priority 3
python add_task.py "Weekly check-in" --due tomorrow --project Marriage

# Full example with everything
python add_task.py "Weekly check-in" \
  --project Marriage \
  --content "Review the week together" \
  --priority 5 \
  --due tomorrow

添加详细描述：

# Multi-line description using heredoc
python add_task.py "Sunday Marriage Check-in" --project Marriage --priority 5 --content "$(cat <<'EOF'
6 Questions Framework:
1. Connection Score (1-10)
2. What Made Me Feel Loved
3. What Hurt or Frustrated Me
4. Body/Aging Struggle This Week
5. Intimacy Check
6. What I Need Next Week

Process:
- Both write answers (10 min)
- Share and listen (15 min)
- Connect physically (5 min)
EOF
)"

优先级：

• 5 =高（红色）
• 3 =中等（黄色）
• 1 =低（蓝色）
• 0 =无（无颜色）

REST API客户端（用于完整系统设置）

⚠️ 重要：使用 ticktick_rest_api.py 而不是 ticktick_setup.pyOAuth客户端（ticktick-py库）当前已损坏，每次运行时都会重新进行身份验证。

# Create entire Health & Marriage tracking system
python ticktick_rest_api.py --setup

# View current status
python ticktick_rest_api.py --status

# Test authentication
python ticktick_rest_api.py --auth

程序化使用（高级）

from ticktick_rest_api import TickTickClient
import os

# Initialize client
client = TickTickClient(
    client_id=os.getenv('TICKTICK_CLIENT_ID'),
    client_secret=os.getenv('TICKTICK_CLIENT_SECRET'),
    redirect_uri='http://127.0.0.1:8080'
)

# Create a task
task = client.create_task(
    title="Important Task",
    content="Task description here",
    priority=5,
    dueDate="2024-12-31T23:59:59+0000",
    timeZone="America/Los_Angeles"
)

# Get all tasks
tasks = client.get_tasks()

# Get all projects
projects = client.get_projects()

项目结构

ticktick-api-client/
├── README.md                  # This file - Main documentation
├── MCP_README.md              # 🤖 MCP Server setup and usage
├── EXAMPLES.md                # 💬 Real-world MCP usage examples
├── CLAUDE.md                  # Guide for Claude Code
├── ticktick_mcp_server.py     # 🆕 MCP server implementation
├── add_task.py                # ⭐ Quick script to add individual tasks
├── ticktick_rest_api.py       # ✅ REST API client (WORKING)
├── ticktick_setup.py          # ❌ OAuth client (BROKEN - use REST API instead)
├── test_ticktick_auth.py      # Authentication testing
├── requirements.txt           # Python dependencies
├── pyproject.toml             # Package metadata
├── LICENSE                    # MIT License
├── .env.example               # Environment variables template
└── .gitignore                 # Git ignore rules

文档

MCP服务器（克劳德桌面）

• MCP_README.md - 🤖 MCP服务器设置 -在Claude Desktop中使用TickTick
• 示例.md - 💬 使用示例 -与克劳德的真实对话

Python命令行界面/库

• 开始.md - ⭐ 从这里开始 -为新用户提供完整的设置指南
• ADDING-TASKS-CLI.md - ⭐ 快速参考 -使用添加任务 ~/bin/tt 命令
• TICKTICK-QUICKSTART.md -5分钟后开始
• TICKTICK设置.md -带示例的完整设置指南
• CLAUDE.md -技术架构和开发指南

API 参考

任务创建

# Daily recurring task
repeat="RRULE:FREQ=DAILY;INTERVAL=1"

# Weekly on Sunday
repeat="RRULE:FREQ=WEEKLY;BYDAY=SU"

# Every 3 days
repeat="RRULE:FREQ=DAILY;INTERVAL=3"

# Weekdays only (Mon-Fri)
repeat="RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR"

优先级

• 5 =高（红色）
• 3 =中等（黄色）
• 1 =低（蓝色）
• 0 =无（无颜色）

故障排除

认证失败

ValueError: TICKTICK_USERNAME and TICKTICK_PASSWORD must be set

修复： 将凭据添加到 .env 文件

任务未显示

• 检查TickTick web/app以验证项目是否已创建
• 运行身份验证测试： python test_ticktick_auth.py
• 删除TickTick中的项目并重新运行安装程序

令牌已过期

令牌缓存在 .ticktick-token.json 和 .token-oauth.如果身份验证失败：

rm .ticktick-token.json .token-oauth
python test_ticktick_auth.py

用例

此库可用于：

• 个人任务管理自动化
• 习惯跟踪系统
• 项目管理集成
• 团队工作流程自动化
• 定制生产力工具
• 健康和保健跟踪
• 定期提醒系统

安全

• 永不承诺 .env 文件到版本控制
• 令牌文件(.ticktick-token.json, .token-oauth)被自动忽略
• OAuth令牌在本地缓存以确保安全
• 凭据仅用于初始身份验证

依赖项

• ticktick-py -官方TickTick Python SDK
• requests -用于REST API的HTTP库
• python-dotenv -环境变量管理

贡献

这是一个参考实现。请随意：

• 根据您的需求进行分叉和定制
• 添加新功能
• 改进错误处理
• 扩展REST API覆盖范围

许可证

MIT许可证-在您的项目中自由使用

链接

• TickTick开发者门户
• TickTick API文档

______________________________________________________________________

专为希望对TickTick工作流程进行程序化控制的自动化爱好者而设计。