ticktick

TickTick MCP Server provides OAuth 2.1 with PKCE authentication to connect Claude Desktop with TickTick tasks and projects. Once authenticated, the server exposes a suite of MCP tools for managing tasks and projects, including listing, creating, updating, and deleting items, as well as searching and filtering. The server stores access tokens locally and automatically refreshes tokens when they expire, enabling continuous use within Claude Desktop. To get started, configure your TickTick credentials either via a ticktick-oauth.keys.json file, environment variables, or system environment variables, with a clear priority order. After building and starting the server, you can verify authentication status using the provided tools and then begin using the authentication management and task/project management tools exposed by the MCP server.

Prerequisites:

• Node.js and npm installed
• Access to TickTick Developer Console to obtain client ID/secret and redirect URI

1. Install dependencies and build

npm install
npm run build

2. Configure credentials (choose one):

• Method 1: ticktick-oauth.keys.json (recommended) Create a file at project root named ticktick-oauth.keys.json with: { "client_id": "your_ticktick_client_id", "client_secret": "your_ticktick_client_secret", "redirect_uri": "http://localhost:8080/callback" }
• Method 2: Environment variables (.env) Create a .env file: TICKTICK_CLIENT_ID=your_ticktick_client_id TICKTICK_CLIENT_SECRET=your_ticktick_client_secret TICKTICK_REDIRECT_URI=http://localhost:8080/callback
• Method 3: System environment variables export TICKTICK_CLIENT_ID=your_ticktick_client_id export TICKTICK_CLIENT_SECRET=your_ticktick_client_secret export TICKTICK_REDIRECT_URI=http://localhost:8080/callback

Configuration Priority:

1. Settings passed directly to the constructor (in code)
2. ticktick-oauth.keys.json file
3. Environment variables (.env) or system environment variables

3. Token storage location (important)

• Tokens are saved to .ticktick-mcp-server-credentials.json, with priority:
  1. Path from TICKTICK_CREDENTIALS_PATH environment variable
  2. User home directory (~/.ticktick-mcp-server-credentials.json)
  3. Current working directory

4. Start authentication flow

npm run start auth

Follow the browser prompts to authorize and save tokens.

5. Verify authentication status

npm run inspector

Then navigate to http://localhost:5173 and use the MCP Inspector to confirm ticktick_auth_status.

Notes and tips:

• Tokens are stored in plaintext in the credentials file; consider encrypting in production.
• The credentials path can be set via TICKTICK_CREDENTIALS_PATH for Claude Desktop environments.
• Ensure the redirect URI registered in TickTick matches http://localhost:8080/callback exactly.
• The integration supports a wide range of TickTick operations, including creating, updating, and deleting tasks and projects, as well as archiving projects and searching tasks.
• When configuring via multiple methods, the priority order determines which values are used.
• The Claude Desktop integration example shows how to reference the server and pass environment variables for authentication context.