<div align="center">

TickTick MCP Server 🎯

TickTick.com | Manage Your Tasks with AI

</div>

A comprehensive MCP (Model Context Protocol) server for managing your TickTick tasks directly from Claude or any MCP-compatible AI assistant.

Features ✨

• Task Management: Create, update, complete, and delete tasks
• Project Management: Create and manage projects/lists
• Smart Scheduling: Generate daily schedules based on task priorities and due dates
• OAuth2 Authentication: Secure authentication with TickTick's official API
• Rich Formatting: Beautiful markdown output for easy reading

Prerequisites

• Python 3.10 or higher
• A TickTick account
• A TickTick Developer App (we'll create this below)

Installation

Step 1: Clone/Copy the Server

# Create directory
mkdir -p ~/ticktick-mcp
cd ~/ticktick-mcp

# Copy the files (ticktick_mcp.py and pyproject.toml)

Step 2: Install Dependencies

# Using pip
pip install mcp httpx pydantic

# Or using the project
cd ~/ticktick-mcp
pip install -e .

Step 3: Register a TickTick Developer App

1. Go to TickTick Developer Portal
2. Log in with your TickTick account
3. Click "+ App Name" to create a new app
4. Enter a name (e.g., "Claude MCP Integration")
5. Important: Set the OAuth Redirect URL to: http://127.0.0.1:8080/callback
6. Click Save
7. Note down your Client ID and Client Secret

Configuration

For Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ticktick": {
      "command": "python",
      "args": ["/path/to/ticktick-mcp/ticktick_mcp.py"],
      "env": {}
    }
  }
}

Using uv (recommended):

{
  "mcpServers": {
    "ticktick": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/ticktick-mcp", "python", "ticktick_mcp.py"]
    }
  }
}

For Other MCP Clients

Run the server directly:

python ticktick_mcp.py

First-Time Setup (OAuth Authentication)

Once the MCP server is connected, use these tools in order:

1. Configure Credentials

Tell Claude:

"Configure TickTick with my credentials: Client ID is YOUR_CLIENT_ID and Client Secret is YOUR_CLIENT_SECRET"

This will:

• Save your credentials securely
• Generate an authorization URL for you to visit

2. Authorize the App

1. Claude will provide an authorization URL
2. Open the URL in your browser
3. Log in to TickTick and click "Allow"
4. You'll be redirected to a URL like: http://127.0.0.1:8080/callback?code=ABCD1234&state=mcp_auth
5. Copy the code parameter (ABCD1234 in this example)

3. Complete Authorization

Tell Claude:

"Complete TickTick authorization with code: ABCD1234"

You're now authenticated! The token is cached for ~6 months.

Available Tools

Authentication

Tool	Description
ticktick_configure	Configure API credentials
ticktick_authorize	Complete OAuth flow
ticktick_check_auth	Check authentication status

Tasks

Tool	Description
ticktick_list_tasks	List all incomplete tasks
ticktick_get_task	Get details of a specific task
ticktick_create_task	Create a new task
ticktick_update_task	Update an existing task
ticktick_complete_task	Mark a task as complete
ticktick_delete_task	Delete a task

Projects

Tool	Description
ticktick_list_projects	List all projects/lists
ticktick_create_project	Create a new project
ticktick_delete_project	Delete a project

Scheduling

Tool	Description
ticktick_schedule_time	Generate a daily schedule
ticktick_get_today	Quick view of today's tasks

Usage Examples

List Your Tasks

"Show me all my TickTick tasks"

Create a Task

"Create a TickTick task: Review Q4 report, due tomorrow, high priority"

Schedule Your Day

"Help me plan my day based on my TickTick tasks"

Create a Project

"Create a new TickTick project called 'Side Business Ideas'"

Complete a Task

"Mark task ID abc123 in project xyz as complete"

Task Priority Levels

Priority	Value	Emoji
None	0	⚪
Low	1	🟢
Medium	3	🟡
High	5	🔴

File Locations

The server stores configuration and tokens in your home directory:

• Configuration: ~/.ticktick-mcp-config.json
• OAuth Token: ~/.ticktick-mcp-token.json

To reset authentication, delete these files.

Troubleshooting

"Not authenticated" Error

Run ticktick_check_auth to verify your authentication status, then re-run the OAuth flow if needed.

"Token expired" Error

Delete ~/.ticktick-mcp-token.json and re-authenticate.

"Rate limit exceeded" Error

Wait a minute before making more requests. TickTick has API rate limits.

"Resource not found" Error

Double-check the task ID and project ID. Use ticktick_list_tasks to see valid IDs.

API Reference

This server uses TickTick's official Open API:

• TickTick Developer Portal
• API Documentation

Contributing

Feel free to extend this server! Some ideas:

• Add support for habits
• Add Pomodoro timer integration
• Add calendar view
• Add recurring task support
• Add tag management tools

License

MIT License - feel free to use and modify!

---

Built with ❤️ for productivity enthusiasts using Claude and TickTick.