TickTick MCP Server

An MCP server that lets your AI assistant manage your TickTick tasks, projects, habits, and more through natural language. Works with Claude Code, Cursor, VS Code, Claude Desktop, and any MCP-compatible client.

Also supports Dida365 (the Chinese version of TickTick).

Features

52 tools across two API layers:

V1 = Official TickTick Open API (OAuth2). V2 = Internal API (session auth) for features not in the public API.

Related MCP server: dida365-agent

Setup

1. Create a TickTick Developer App

1. Go to developer.ticktick.com/manage

2. Click + Create App

3. Set Redirect URI to: http://localhost:42813/callback

4. Note your Client ID and Client Secret

2. Install and Authenticate

git clone https://github.com/chrisvanek/ticktick-mcp-ratv.git
cd ticktick-mcp-ratv
npm install && npm run build

# Run the interactive setup wizard
node build/index.js auth

The wizard guides you through:

1. TickTick login (email + password) — enables V2 features (tags, habits, focus, completed tasks)

2. OAuth2 flow (Client ID + Secret + browser auth) — enables V1 features (projects, tasks)

Credentials are saved to a local .env file (excluded from git).

3. Connect to Your AI Client

Add the server to your MCP client config. Replace the placeholder values with the credentials from your .env file.

CLI (recommended):

claude mcp add ticktick-mcp-server \
  node /absolute/path/to/ticktick-mcp-ratv/build/index.js \
  -e TICKTICK_CLIENT_ID=your_client_id \
  -e TICKTICK_CLIENT_SECRET=your_client_secret \
  -e TICKTICK_ACCESS_TOKEN=your_access_token \
  -e TICKTICK_REFRESH_TOKEN=your_refresh_token \
  -e TICKTICK_USERNAME=your_email \
  -e TICKTICK_PASSWORD=your_password \
  -e TICKTICK_DEVICE_ID=your_device_id \
  -s user

Use -s user (available everywhere), -s project (shared with team), or -s local (single project).

Config file (~/.claude.json or .mcp.json):

{
  "mcpServers": {
    "ticktick": {
      "command": "node",
      "args": ["/absolute/path/to/ticktick-mcp-ratv/build/index.js"],
      "env": {
        "TICKTICK_CLIENT_ID": "your_client_id",
        "TICKTICK_CLIENT_SECRET": "your_client_secret",
        "TICKTICK_ACCESS_TOKEN": "your_access_token",
        "TICKTICK_REFRESH_TOKEN": "your_refresh_token",
        "TICKTICK_USERNAME": "your_email",
        "TICKTICK_PASSWORD": "your_password",
        "TICKTICK_DEVICE_ID": "your_device_id"
      }
    }
  }
}

Verify with /mcp in Claude Code.

Create or edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "ticktick": {
      "command": "node",
      "args": ["/absolute/path/to/ticktick-mcp-ratv/build/index.js"],
      "env": {
        "TICKTICK_CLIENT_ID": "your_client_id",
        "TICKTICK_CLIENT_SECRET": "your_client_secret",
        "TICKTICK_ACCESS_TOKEN": "your_access_token",
        "TICKTICK_REFRESH_TOKEN": "your_refresh_token",
        "TICKTICK_USERNAME": "your_email",
        "TICKTICK_PASSWORD": "your_password",
        "TICKTICK_DEVICE_ID": "your_device_id"
      }
    }
  }
}

Restart Cursor after saving.

Requires VS Code 1.99+ with GitHub Copilot. Create .vscode/mcp.json:

{
  "servers": {
    "ticktick": {
      "command": "node",
      "args": ["/absolute/path/to/ticktick-mcp-ratv/build/index.js"],
      "env": {
        "TICKTICK_CLIENT_ID": "your_client_id",
        "TICKTICK_CLIENT_SECRET": "your_client_secret",
        "TICKTICK_ACCESS_TOKEN": "your_access_token",
        "TICKTICK_REFRESH_TOKEN": "your_refresh_token",
        "TICKTICK_USERNAME": "your_email",
        "TICKTICK_PASSWORD": "your_password",
        "TICKTICK_DEVICE_ID": "your_device_id"
      }
    }
  }
}

Edit the config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %AppData%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ticktick": {
      "command": "node",
      "args": ["/absolute/path/to/ticktick-mcp-ratv/build/index.js"],
      "env": {
        "TICKTICK_CLIENT_ID": "your_client_id",
        "TICKTICK_CLIENT_SECRET": "your_client_secret",
        "TICKTICK_ACCESS_TOKEN": "your_access_token",
        "TICKTICK_REFRESH_TOKEN": "your_refresh_token",
        "TICKTICK_USERNAME": "your_email",
        "TICKTICK_PASSWORD": "your_password",
        "TICKTICK_DEVICE_ID": "your_device_id"
      }
    }
  }
}

Quit and relaunch Claude Desktop (Cmd+Q / Alt+F4).

Open the Cline panel > MCP Servers icon > Configure, then add:

{
  "mcpServers": {
    "ticktick": {
      "command": "node",
      "args": ["/absolute/path/to/ticktick-mcp-ratv/build/index.js"],
      "env": {
        "TICKTICK_CLIENT_ID": "your_client_id",
        "TICKTICK_CLIENT_SECRET": "your_client_secret",
        "TICKTICK_ACCESS_TOKEN": "your_access_token",
        "TICKTICK_REFRESH_TOKEN": "your_refresh_token",
        "TICKTICK_USERNAME": "your_email",
        "TICKTICK_PASSWORD": "your_password",
        "TICKTICK_DEVICE_ID": "your_device_id"
      }
    }
  }
}

Dida365 (China)

Add TICKTICK_HOST=dida365 to your environment variables. This routes API calls to api.dida365.com.

Node Version Managers (nvm, fnm, etc.)

If node doesn't resolve in your MCP client, use the full path:

"command": "/Users/you/.nvm/versions/node/v22.0.0/bin/node"

Usage Examples

Once connected, just talk naturally. Here are examples organized by what you can do:

Morning Planning

"Give me my daily summary"

"What's overdue?"

"What do I have due this week?"

"Show me all high priority tasks"

Creating Tasks

"Create a task called 'Review PR #42' in my Work project, due tomorrow, high priority"

"Add a task 'Buy groceries' to Personal with subtasks: milk, eggs, bread, butter"

"Create a recurring task 'Weekly standup notes' every Monday in my Work project"

"Create these tasks in my Work project: Review design mockups, Update API docs, Fix login bug"

Managing Tasks

"Mark the 'Send invoice' task as complete"

"Move 'Design review' to my Work project"

"Make 'Write tests' a subtask of 'Ship v2'"

"What tasks did I complete last week?"

Search & Filter

"Search for any tasks mentioning 'budget'"

"Show me all medium priority tasks"

"What tasks are due in the next 3 days?"

"Show me all tasks in my Personal project that have a due date"

Projects

"List all my projects"

"Create a new project called 'Q2 Goals' with a kanban view"

"Show me everything in my Work project — tasks, columns, the works"

Tags

"Show me all my tags"

"Create a tag called 'urgent' with a red color"

"Rename the 'bug' tag to 'bugfix'"

"Merge the 'todo' tag into 'backlog'"

Habits

"What habits do I have?"

"Check in my 'Drink water' habit for today"

"Create a habit called 'Read' with a goal of 30 pages per day"

"Show my check-in history for all habits since January"

Focus & Productivity

"Show my focus time heatmap for this month"

"How is my focus time distributed across tags?"

"What are my productivity stats?"

Organization

"List my project folders"

"Create a folder called 'Side Projects'"

"Show the kanban columns in my Sprint project"

"What's in my trash?"

Environment Variables

Security note: The V2 API requires your TickTick username and password. These are stored as environment variables and never logged or transmitted anywhere except directly to TickTick's authentication endpoint. The .env file is created with restricted permissions (owner-only read/write).

About TICKTICK_DEVICE_ID: The V2 internal API authenticates a "device" via the x-device request header. If the device id is empty or unrecognized, TickTick rejects the login with a misleading username_password_not_match error — even when your credentials are correct. The server sends a non-empty device id to avoid this. If you don't set TICKTICK_DEVICE_ID, a random 24-character hex id is generated automatically on each launch; setting a stable value is recommended so TickTick doesn't treat every restart as a brand-new device. Any 24-char hex string works — or reuse the id your TickTick web client already uses (browser DevTools → Application → Local Storage → deviceAnalyticsData.id).

All 52 Tools

Reference

Task priority values: 0 = None, 1 = Low, 3 = Medium, 5 = High

Date format: yyyy-MM-dd'T'HH:mm:ssZ (e.g. 2025-03-15T09:00:00+0000)

Recurrence rules: Standard RRULE format (e.g. RRULE:FREQ=DAILY;INTERVAL=1)

Development

npm install       # Install dependencies
npm run build     # Compile TypeScript
npm run dev       # Watch mode
npm run clean     # Remove build output

Adding a Tool

1. Add your tool in the appropriate file under src/tools/

2. Use server.registerTool() with a Zod input schema

3. It's automatically available to all MCP clients

Architecture

src/
├── index.ts              # Entry point + auth CLI routing
├── config.ts             # Environment variable loader
├── client.ts             # V1 API client (OAuth2)
├── client-v2.ts          # V2 API client (session auth)
├── types.ts              # TypeScript interfaces
├── auth-cli.ts           # Interactive auth wizard
├── auth/oauth.ts         # OAuth2 flow implementation
└── tools/
    ├── project-tools.ts  # Project CRUD (V1)
    ├── task-tools.ts     # Task CRUD (V1)
    ├── smart-tools.ts    # Smart queries & GTD (V1)
    ├── tag-tools.ts      # Tag management (V2)
    ├── habit-tools.ts    # Habit tracking (V2)
    ├── focus-tools.ts    # Focus/Pomodoro stats (V2)
    ├── column-tools.ts   # Kanban columns (V2)
    ├── folder-tools.ts   # Project folders (V2)
    └── v2-task-tools.ts  # Completed tasks, move, user (V2)

Both API clients handle auth transparently — expired tokens are refreshed automatically on 401 responses.

Troubleshooting

Contributing

1. Fork the repo

2. Create a feature branch

3. Make your changes and run npm run build

4. Open a pull request

License

MIT — see LICENSE.

Acknowledgments

• TickTick Open API

• Model Context Protocol

• Inspired by jacepark12/ticktick-mcp and jen6/ticktick-mcp