TickTick MCP Server

# TickTick MCP Server > Manage your TickTick tasks directly from Claude Desktop using the Model Context Protocol [](https://modelcontextprotocol.io) [](https://www.python.org/downloads/) ## What is This? An MCP (Model Context Protocol) server that connects TickTick to Claude Desktop, allowing you to manage tasks through natural conversation: **Instead of:** ```bash python add_task.py "Buy groceries" --priority 5 --due tomorrow ``` **You can:** ``` You: "Add a high-priority task to buy groceries tomorrow" Claude: ✓ Created task: Buy groceries Priority: High Due: 2025-11-17 ``` ## Features **Tools:** - `add_task` - Create tasks with natural language - `list_tasks` - View tasks by project or all at once - `complete_task` - Mark tasks as done - `get_task_details` - View full task information - `list_projects` - See all your projects - `create_project` - Make new projects **Resources:** - `ticktick://status` - Real-time overview of tasks and projects ## Prerequisites 1. **TickTick Developer Account** - Go to https://developer.ticktick.com/manage - Create a new app - Note your `Client ID` and `Client Secret` - Set redirect URI to: `http://127.0.0.1:8080` 2. **Python 3.8+** 3. **Claude Desktop** (for MCP integration) ## Installation ### 1. Clone & Install Dependencies ```bash git clone <your-repo-url> cd ticktick-api-client pip install -r requirements.txt ``` ### 2. Install MCP Package ```bash pip install "mcp[cli]" ``` ### 3. Set Up Environment Variables Create a `.env` file: ```bash TICKTICK_CLIENT_ID=your_client_id_here TICKTICK_CLIENT_SECRET=your_client_secret_here TICKTICK_REDIRECT_URI=http://127.0.0.1:8080 ``` ### 4. Complete OAuth Authentication **IMPORTANT:** Run this BEFORE setting up Claude Desktop: ```bash python ticktick_rest_api.py --auth ``` This will: - Open your browser for TickTick authorization - Save your token to `.ticktick-token.json` - Token lasts ~165 days, no re-authentication needed ### 5. Install to Claude Desktop ```bash # Using uv (recommended) uvx mcp install ticktick_mcp_server.py # Or using mcp directly mcp install ticktick_mcp_server.py ``` This adds the server to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`). **Or manually add to config:** ```json { "mcpServers": { "ticktick": { "command": "python", "args": ["/absolute/path/to/ticktick_mcp_server.py"], "env": { "TICKTICK_CLIENT_ID": "your_client_id", "TICKTICK_CLIENT_SECRET": "your_client_secret", "TICKTICK_REDIRECT_URI": "http://127.0.0.1:8080" } } } } ``` ### 6. Restart Claude Desktop Quit and reopen Claude Desktop. You should see "TickTick" in the MCP servers list. ## Usage Examples **In Claude Desktop:** ``` You: "Create a task to call mom tomorrow at 2pm" Claude: [uses add_task tool] ✓ Created task: Call mom Due: 2025-11-17T14:00:00 ``` ``` You: "Show me my Health project tasks" Claude: [uses list_tasks tool with project="Health"] Found 5 task(s): ○ Monday: 30 min Strength/Stretch Project: Health Due: 2025-11-18T07:00:00 Priority: High ... ``` ``` You: "Mark 'Download Blueheart App' as complete" Claude: [uses complete_task tool] ✓ Completed task: Download Blueheart App ``` ``` You: "What's my current TickTick status?" Claude: [reads ticktick://status resource] TickTick Status Overview ======================================== Total Tasks: 23 Active: 18 Completed: 5 Projects (3): • Marriage: 4 tasks • Health: 7 tasks • Milestones: 3 tasks ``` ## Development & Testing ### Test Locally with MCP Inspector ```bash # Using uv uv run mcp dev ticktick_mcp_server.py # Or using mcp directly mcp dev ticktick_mcp_server.py ``` This opens an interactive web interface to test all tools and resources. ### Test with CLI Scripts The original Python client still works for automation: ```bash # Add task via CLI python add_task.py "Task title" --content "Description" --priority 5 # View status python ticktick_rest_api.py --status ``` ## Project Structure ``` ticktick-api-client/ ├── ticktick_mcp_server.py # MCP server implementation ├── ticktick_rest_api.py # REST API client (used by MCP server) ├── add_task.py # CLI tool for adding tasks ├── requirements.txt # Python dependencies ├── .env # Your credentials (gitignored) ├── .ticktick-token.json # OAuth token cache (gitignored) ├── README.md # Original project README └── MCP_README.md # This file ``` ## Troubleshooting ### "Not authenticated" Error Run the auth flow first: ```bash python ticktick_rest_api.py --auth ``` Make sure `.ticktick-token.json` is created before using the MCP server. ### Claude Desktop Can't Find Server 1. Check the config path: `~/Library/Application Support/Claude/claude_desktop_config.json` 2. Verify paths are absolute (not relative) 3. Restart Claude Desktop after config changes ### Token Expired Delete the token file and re-authenticate: ```bash rm .ticktick-token.json python ticktick_rest_api.py --auth ``` ### MCP Server Crashes Check Claude Desktop logs: ```bash tail -f ~/Library/Logs/Claude/mcp*.log ``` ## API Limits TickTick API has rate limits: - 120 requests per minute - 5000 requests per day The MCP server doesn't implement rate limiting yet. For heavy use, consider adding request throttling. ## Contributing Contributions welcome! Ideas: - [ ] Add rate limiting - [ ] Support for tags and labels - [ ] Task reminders and notifications - [ ] Bulk operations - [ ] Advanced filtering (by date range, priority, etc.) - [ ] Subtask support ## License MIT License - see LICENSE file for details ## Credits Built with: - [Model Context Protocol](https://modelcontextprotocol.io) - [FastMCP](https://github.com/modelcontextprotocol/python-sdk) - [TickTick Open API](https://developer.ticktick.com/api) ## Related - Original Python client: See `README.md` - TickTick Developer Docs: https://developer.ticktick.com/ - MCP Specification: https://spec.modelcontextprotocol.io/