TickTick API客户端和MCP服务器
TickTick的Python客户端库 使用它的两种方法:
- MCP服务器 -通过自然对话与Claude Desktop一起使用TickTick
- 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交互的方法：
- MCP服务器 (
ticktick_mcp_server.py)Claude Desktop的模型上下文协议服务器 - REST API客户端 (
ticktick_rest_api.py)-用于自动化的直接REST API实现 - OAuth客户端 (
ticktick_setup.py)-使用ticktick-py图书馆（目前已损坏）
特性
MCP服务器：
- 自然语言任务创建和管理
- 通过Claude Desktop实现对话界面
- 实时任务状态和项目概述
- 任务和项目的模糊搜索
Python客户端：
- 创建和管理TickTick项目（列表）
- 使用RRULE语法创建重复任务
- 设置任务优先级、截止日期和提醒
- 带有令牌缓存的OAuth2身份验证
- 用于高级用例的REST API实现
- 用于快速添加任务的命令行工具
快速入门（5分钟）
1.安装依赖项
pip install -r requirements.txt2.配置凭据
复制 .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凭据：
- 首选https://developer.ticktick.com/manage
- 点击“+应用程序名称”并创建应用程序
- 将重定向URI设置为：
http://127.0.0.1:8080 - 复制您的客户端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 SDKrequests-用于REST API的HTTP库python-dotenv-环境变量管理
贡献
这是一个参考实现。请随意：
- 根据您的需求进行分叉和定制
- 添加新功能
- 改进错误处理
- 扩展REST API覆盖范围
许可证
MIT许可证-在您的项目中自由使用
链接
______________________________________________________________________
专为希望对TickTick工作流程进行程序化控制的自动化爱好者而设计。