TickTick Model Context Protocol (MCP) Server

TickTick uses the OAuth2 protocol to authorize access to user data. The process involves three main steps:

1. Redirect to Authorization Page: Send the user to the TickTick authorization URL with your application credentials and requested scopes.
2. Receive Authorization Code: After the user grants permission, TickTick redirects them back to your redirect_uri with a code and the original state parameter.
3. Exchange Code for Access Token: Make a server-side POST request to exchange the authorization code for a usable access_token.

To use the TickTick MCP server with Claude for Desktop, add the server configuration to your claude_desktop_config.json file using absolute paths.

File Locations:

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

Configuration Structure:

{
   "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 after saving the file. You will see a 🔨 icon when tools are available.

{
   "mcpServers": {
      "ticktick": {
         "command": "/usr/local/bin/uv",
         "args": ["run", "--directory", "/Users/username/ticktick-mcp", "-m", "ticktick_mcp.cli", "run"]
      }
   }
}

Redirect the user to https://ticktick.com/oauth/authorize using the following query parameters:

Example URL: https://ticktick.com/oauth/authorize?scope=scope&client_id=client_id&state=state&redirect_uri=redirect_uri&response_type=code

Once the user authorizes your app, TickTick redirects them to your configured redirect_uri. You must extract the following query parameters from the URL:

For the China version of TickTick (Dida365), follow these steps:

1. Register your application at the Dida365 Developer Center.
2. Set the redirect URI to http://localhost:8000/callback.
3. Manually add the following 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'

4. Run the standard authentication command: uv run -m ticktick_mcp.cli auth.

The server uses OAuth2. To set it up:

1. Register your app at the TickTick Developer Center.
2. Set the redirect URI to http://localhost:8000/callback.
3. Run the CLI auth command:

   uv run -m ticktick_mcp.cli auth

4. Enter your Client ID and Client Secret when prompted.
5. Authorize via the browser window that opens.

Tokens are automatically saved to a .env file and refreshed automatically.

To install the TickTick MCP server, you need Python 3.10+, uv, and TickTick API credentials. Follow these steps:

1. Clone the repository:

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

2. Set up the environment with uv:

   # Install uv if not present
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Create and activate virtual environment
   uv venv
   # On macOS/Linux:
   source .venv/bin/activate
   # On Windows:
   .venv\Scripts\activate
   
   # Install the package in editable mode
   uv pip install -e .

3. Authenticate: Run the authentication flow to link your TickTick account:

   uv run -m ticktick_mcp.cli auth

The server provides specialized tools based on the GTD framework to help focus on immediate priorities:

• get_engaged_tasks: Returns tasks that require immediate attention. This includes tasks with High priority (5), tasks that are due today, or tasks that are overdue.
• get_next_tasks: Returns tasks for upcoming focus. This includes tasks with Medium priority (3) or tasks due tomorrow.

The server requires a TICKTICK_ACCESS_TOKEN to communicate with the TickTick API. This token must be present in a .env file in the working directory.

If the token is missing or expired, you must run the authentication CLI command:

uv run -m ticktick_mcp.cli auth

Retrieve the details of a specific task using its taskId and the projectId it belongs to.

Endpoint: GET /open/v1/project/{projectId}/task/{taskId}

Path Parameters:

• projectId (required): Project identifier.
• taskId (required): Task identifier.

Responses:

• 200 OK: Returns the [Task] object.
• 401 Unauthorized: Authentication failed.
• 403 Forbidden: Insufficient permissions.
• 404 Not Found: Task or Project not found.

GET /open/v1/project/{{projectId}}/task/{{taskId}} HTTP/1.1
Host: api.ticktick.com
Authorization: Bearer {{token}}