ticktick-mcp-server

日本語版はこちら

TickTick MCP (Model Context Protocol) Server - An MCP server for using TickTick task management features from Claude

Overview

This MCP server enables integration with the TickTick task management platform from Claude Desktop. It implements secure authentication using OAuth 2.1 with PKCE (Proof Key for Code Exchange) and provides comprehensive task and project management capabilities.

Authentication and Authorization

OAuth 2.1 with PKCE

This server adopts the OAuth 2.1 with PKCE protocol for secure authentication:

1. PKCE Authentication Flow

   • Generates code_verifier and code_challenge at the start of authentication
   • Displays TickTick authentication screen in browser
   • Obtains authorization code after user approval
   • Exchanges tokens using authorization code and code_verifier

2. Token Storage

   • Stores access tokens in .ticktick-mcp-server-credentials.json file
   • ⚠️ Security Warning: Tokens are currently stored in plaintext. For production use, implementing encryption is recommended
   • Never expose access tokens publicly

3. Automatic Token Refresh

   • MCP server automatically checks token expiration
   • Obtains new access token using refresh token when expired

Setup Instructions

1. Configure Authentication Credentials

Configure credentials obtained from the TickTick Developer Console. Choose from one of three methods:

Method 1: ticktick-oauth.keys.json (Recommended)

Create a ticktick-oauth.keys.json file in the project root:

{
  "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 in the project root:

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

Set directly in your shell:

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 (specified in code)
2. ticktick-oauth.keys.json file
3. Environment variables (.env file or system environment variables)

Note:

• When configured through multiple methods, loading follows the priority order above
• For security, these files are added to .gitignore and will not be committed to the repository
• Replace your_ticktick_client_id and your_ticktick_client_secret with actual values

Token Storage Location Configuration (Important)

Authentication tokens are saved according to the following priority:

1. Path specified by TICKTICK_CREDENTIALS_PATH environment variable (recommended)