TickTick MCP server for AI agents

The TickTick MCP server provides a powerful interface between AI assistants and the TickTick task management platform. It enhances TickTick's capabilities by offering improved filtering and comprehensive access to task management functions through the Model Context Protocol (MCP).

Installation

Prerequisites

Python 3.10 or higher
TickTick account and API credentials

Setting Up API Credentials

Register a TickTick application to obtain API credentials:
- Visit the TickTick OpenAPI Documentation and log in
- Click "Manage Apps" in the top right corner
- Create a new app by clicking "+App Name" and provide a name (e.g., "MCP Server")
- Edit the app details and note down the generated Client ID and Client Secret
- For the OAuth Redirect URL, enter something like http://localhost:8080/redirect (which will be used during authentication)
Configure environment variables:
- Create a directory at ~/.config/ticktick-mcp/ if it doesn't exist
- Create a .env file in this directory with the following content:

TICKTICK_CLIENT_ID=your_client_id
TICKTICK_CLIENT_SECRET=your_client_secret
TICKTICK_REDIRECT_URI=your_redirect_uri
TICKTICK_USERNAME=your_ticktick_email
TICKTICK_PASSWORD=your_ticktick_password

First-Time Authentication

The first time you run the server:

A browser window may open or a URL will be displayed in the console
Visit this URL, log into TickTick, and authorize the application
After authorization, you'll be redirected to your specified redirect URI
Copy the full redirected URL and paste it into the terminal when prompted
A .token-oauth file will be created to cache your authorization token (valid for ~6 months)

Running the Server

The recommended way to run the server is via an MCP client:

Configure your MCP client (such as Claude Desktop or VS Code Agent Mode) with this configuration:

{
 "mcpServers": {
   "ticktick": {
     "command": "uvx",
     "args": [
       "--from",
       "git+https://github.com/jen6/ticktick-mcp.git",
       "ticktick-mcp"
     ]
   }
 }
}

Using the Server

Task Management

The server provides comprehensive tools for managing TickTick tasks:

Creating Tasks

// Create a new task
mcp.ticktick.ticktick_create_task({
  title: "Complete project report",
  content: "Include all quarterly metrics",
  priority: 3,
  dueDate: "2023-12-31T17:00:00"
});

Updating Tasks

// Update an existing task
mcp.ticktick.ticktick_update_task({
  task_object: {
    id: "task_id_here",
    title: "Updated title",
    priority: 5
  }
});

Completing and Moving Tasks

// Mark a task as complete
mcp.ticktick.ticktick_complete_task({
  task_id: "task_id_here"
});

// Move a task to a different project
mcp.ticktick.ticktick_move_task({
  task_id: "task_id_here",
  new_project_id: "project_id_here"
});

Task Retrieval and Filtering

The server offers powerful options for retrieving and filtering tasks:

// Get all uncompleted tasks from a specific project
mcp.ticktick.ticktick_get_tasks_from_project({
  project_id: "project_id_here"
});

// Filter tasks by various criteria
mcp.ticktick.ticktick_filter_tasks({
  filter_criteria: {
    status: "uncompleted",
    priority: 5,
    due_end_date: "2023-12-31",
    tag_label: "important",
    sort_by_priority: true
  }
});

Helper Tools

The server includes utilities to make working with TickTick's date format easier:

// Convert ISO datetime to TickTick format
mcp.ticktick.ticktick_convert_datetime_to_ticktick_format({
  datetime_iso_string: "2023-12-31T17:00:00",
  tz: "America/New_York"
});

Example Agent Implementation

You can create AI agents that use this server to help manage tasks. For example, a daily stand-up agent could:

Fetch current tasks due today
Present them to the user in a daily briefing
Help the user break down large tasks into subtasks
Add these subtasks to TickTick

This enables powerful AI-assisted task management workflows that integrate directly with your TickTick account.

How to add this MCP server to 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 > MCP and click "Add new global MCP server".

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

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

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 explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.