TickTick MCP server

This MCP server for TickTick enables you to interact with your TickTick task management system directly through Claude and other MCP clients. It provides a seamless bridge between AI assistants and your task management workflow.

Installation

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)

Setup Steps

1. Clone the repository:

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

2. 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 .
   

3. Authenticate with TickTick:

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

4. Test your configuration:

   uv run test_server.py
   

Authentication

TickTick Authentication

1. Register your application at the TickTick Developer Center

   • Set the redirect URI to http://localhost:8000/callback
   • Note your Client ID and Client Secret

2. Run the authentication command:

   uv run -m ticktick_mcp.cli auth
   

3. Follow the prompts to enter your Client ID and Client Secret

4. A browser window will open for you to authorize the application

5. After authorizing, your access tokens will be automatically saved to the .env file

Dida365 Authentication

For users of Dida365 (China version of TickTick):

1. Register your application at the Dida365 Developer Center

   • Set the redirect URI to http://localhost:8000/callback

2. Add 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'
   

3. Follow the same authentication steps as for TickTick

Usage with Claude for Desktop

1. Install Claude for Desktop

2. 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
   

3. 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"]
         }
      }
   }
   

4. Restart Claude for Desktop

Available MCP Tools

The server provides the following tools for interacting with TickTick:

Project Management

• get_projects - List all your TickTick projects
• get_project - Get details about a specific project
• create_project - Create a new project
• delete_project - Delete a project

Task Management

• get_project_tasks - List all tasks in a project
• get_task - Get details about a specific task
• create_task - Create a new task
• update_task - Update an existing task
• complete_task - Mark a task as complete
• delete_task - Delete a task

Example Prompts for Claude

Here are some example prompts to use with Claude after connecting the TickTick MCP server:

• "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?"

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.