TickTick MCP server for AI agents

A Model Context Protocol (MCP) server for TickTick that enables interaction with your task management system directly through Claude and other MCP clients. This integration allows you to view, create, update, and manage your TickTick tasks and projects through natural language.

Prerequisites

Python 3.10 or higher
uv - Fast Python package installer and resolver
TickTick account with API access
TickTick API credentials (Client ID, Client Secret, Access Token)

Installation

Clone and Setup

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

Install with uv

# Install uv if you don't have it already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a virtual environment
uv venv

# Activate the virtual environment
# On macOS/Linux:
source .venv/bin/activate
# On Windows:
.venv\Scripts\activate

# Install the package
uv pip install -e .

Authenticate with TickTick

# Run the authentication flow
uv run -m ticktick_mcp.cli auth

This will:

Ask for your TickTick Client ID and Client Secret
Open a browser window for you to log in to TickTick
Automatically save your access tokens to a .env file

Test Your Configuration

uv run test_server.py

Authentication Process

TickTick Authentication

Register your application at the TickTick Developer Center
- Set the redirect URI to http://localhost:8000/callback
- Note your Client ID and Client Secret
Run the authentication command:
```
uv run -m ticktick_mcp.cli auth
```
Follow the prompts and authorize the application with your TickTick account

Dida365 Authentication

For users of 滴答清单 - Dida365 (China version of TickTick):

Add these environment variables to your .env file:

TICKTICK_BASE_URL='https://api.dida365.com/open/v1'
TICKTICK_AUTH_URL='https://dida365.com/oauth/authorize'
TICKTICK_TOKEN_URL='https://dida365.com/oauth/token'

Follow the same authentication steps as for TickTick

Setting Up with Claude for Desktop

Install Claude for Desktop

Edit your Claude for Desktop configuration file:

macOS:

nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows:

notepad %APPDATA%\Claude\claude_desktop_config.json

Add the TickTick MCP server configuration, using absolute paths:

{
   "mcpServers": {
      "ticktick": {
         "command": "<absolute path to uv>",
         "args": ["run", "--directory", "<absolute path to ticktick-mcp directory>", "-m", "ticktick_mcp.cli", "run"]
      }
   }
}

Restart Claude for Desktop

Available MCP Tools

Core Project and Task Management

Tool	Description	Parameters
`get_projects`	List all your TickTick projects	None
`get_project`	Get details about a specific project	`project_id`
`get_project_tasks`	List all tasks in a project	`project_id`
`get_task`	Get details about a specific task	`project_id`, `task_id`
`create_task`	Create a new task	`title`, `project_id`, `content` (optional), `start_date` (optional), `due_date` (optional), `priority` (optional)
`update_task`	Update an existing task	`task_id`, `project_id`, `title` (optional), `content` (optional), `start_date` (optional), `due_date` (optional), `priority` (optional)
`complete_task`	Mark a task as complete	`project_id`, `task_id`
`delete_task`	Delete a task	`project_id`, `task_id`
`create_project`	Create a new project	`name`, `color` (optional), `view_mode` (optional)
`delete_project`	Delete a project	`project_id`

Task Retrieval & Search

Tool	Description	Parameters
`get_all_tasks`	Get all tasks from all projects	None
`get_tasks_by_priority`	Get tasks filtered by priority level	`priority_id` (0: None, 1: Low, 3: Medium, 5: High)
`search_tasks`	Search tasks by title, content, or subtasks	`search_term`

Date-Based Task Retrieval

Tool	Description	Parameters
`get_tasks_due_today`	Get all tasks due today	None
`get_tasks_due_tomorrow`	Get all tasks due tomorrow	None
`get_tasks_due_in_days`	Get tasks due in exactly X days	`days` (0 = today, 1 = tomorrow, etc.)
`get_tasks_due_this_week`	Get tasks due within the next 7 days	None
`get_overdue_tasks`	Get all overdue tasks	None

Getting Things Done (GTD) Framework

Tool	Description	Parameters
`get_engaged_tasks`	Get "engaged" tasks (high priority or overdue)	None
`get_next_tasks`	Get "next" tasks (medium priority or due tomorrow)	None
`batch_create_tasks`	Create multiple tasks at once	`tasks` (list of task dictionaries)

Example Prompts for Claude

General Task Management

"Show me all my TickTick projects"
"Create a new task called 'Finish MCP server documentation' in my work project with high priority"
"List all tasks in my personal project"
"Mark the task 'Buy groceries' as complete"
"Create a new project called 'Vacation Planning' with a blue color"
"When is my next deadline in TickTick?"

Task Filtering

"What tasks do I have due today?"
"Show me everything that's overdue"
"Show me all tasks due this week"
"Search for tasks about 'project alpha'"
"Show me all tasks with 'client' in the title or description"
"Show me all my high priority tasks"

GTD Workflow

"Time block the rest of my day from 2-8pm with items from my engaged list"
"Walk me through my next actions and help my identify what I should focus on tomorrow?"
"Break down this project into 5 smaller actionable tasks"

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "ticktick" '{"command":"uv","args":["run","--directory","{absolute_path_to_ticktick-mcp_directory}","-m","ticktick_mcp.cli","run"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "ticktick": {
            "command": "uv",
            "args": [
                "run",
                "--directory",
                "{absolute_path_to_ticktick-mcp_directory}",
                "-m",
                "ticktick_mcp.cli",
                "run"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

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

2. Add this to your configuration file:

{
    "mcpServers": {
        "ticktick": {
            "command": "uv",
            "args": [
                "run",
                "--directory",
                "{absolute_path_to_ticktick-mcp_directory}",
                "-m",
                "ticktick_mcp.cli",
                "run"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect