What is Ticktick Mcp Server

ticktick-mcp-server is a Model Context Protocol (MCP) server designed for integration with the TickTick task management service, enabling users to manage their tasks and projects efficiently.

Use cases

Use cases for ticktick-mcp-server include managing daily tasks, tracking overdue tasks, organizing projects, and integrating task management into other applications or services.

How to use

To use ticktick-mcp-server, install the necessary dependencies, configure the environment for authentication (either via OAuth or username/password), build the project, and then run it in development or production mode.

Key features

Key features include listing tasks and projects with enhanced display, creating, updating, and deleting tasks, marking tasks as completed, timezone handling for accurate due date calculations, and support for OAuth and username/password authentication.

Where to use

ticktick-mcp-server can be used in various fields such as personal productivity, project management, and task organization, making it suitable for individuals and teams looking to streamline their workflow.

TickTick MCP Server

A Model Context Protocol (MCP) server that provides integration with TickTick task management service.

Features

• List tasks and projects with enhanced display (human-readable priorities)
• Create, update, and delete tasks
• Mark tasks as completed
• Get specific task details
• Timezone handling with manual D+1 adjustment for accurate due date calculations
• Get overdue tasks with configurable timezone offset
• Get today’s tasks with proper timezone compensation
• OAuth and username/password authentication support
• Full TypeScript support with proper error handling

Setup

1. Install dependencies:

npm install

2. Create environment configuration:

cp .env.example .env

3. Configure authentication in .env:

Option A: OAuth (Recommended)

TICKTICK_ACCESS_TOKEN=your_oauth_access_token
TICKTICK_REFRESH_TOKEN=your_refresh_token
TICKTICK_CLIENT_ID=your_client_id
TICKTICK_CLIENT_SECRET=your_client_secret

Option B: Username/Password

TICKTICK_USERNAME=your_ticktick_username
TICKTICK_PASSWORD=your_ticktick_password

For OAuth setup, see OAUTH_SETUP.md or use the helper:

node oauth-helper.js

4. Build the project:

npm run build

Usage

Development

npm run dev

Production

npm start

Available Tools

• get_tasks - Get all tasks or tasks from a specific project (with enhanced display)
• get_overdue_tasks - Get overdue tasks with timezone compensation (configurable offset, defaults to UTC+8 - adjust for your timezone)
• get_todays_tasks - Get tasks due today with D+1 timezone adjustment
• get_projects - Get all projects from TickTick
• create_task - Create a new task with priority, tags, due dates
• update_task - Update an existing task
• delete_task - Delete a task
• complete_task - Mark a task as completed
• get_task - Get a specific task by ID

Timezone Handling

This server includes manual timezone workarounds to handle TickTick’s timezone inconsistencies:

• D+1 Adjustment: Due dates are automatically adjusted by adding 1 day to compensate for timezone differences
• Configurable Offset: get_overdue_tasks accepts a timezoneOffsetHours parameter
  • Default: 8 (UTC+8) - Change this for your timezone!
  • Examples:
    • timezoneOffsetHours: -5 for EST (UTC-5)
    • timezoneOffsetHours: 0 for UTC
    • timezoneOffsetHours: 9 for JST (UTC+9)
    • timezoneOffsetHours: 1 for CET (UTC+1)
• All-day vs Timed Tasks: Different handling for all-day tasks vs specific time tasks
• Enhanced Display: Tasks include human-readable priority text (None, Low, Medium, High)

Important: The default timezone offset is set to UTC+8. Make sure to specify your correct timezone offset when calling get_overdue_tasks to get accurate results for your location.

MCP Integration

Claude Desktop (with Claude Desktop app)

Add this server to your MCP client configuration file:

Location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

{
  "mcpServers": {
    "ticktick": {
      "command": "node",
      "args": [
        "/path/to/ticktick-mcp-server/dist/index.js"
      ],
      "env": {
        "TICKTICK_ACCESS_TOKEN": "your_oauth_token",
        "TICKTICK_REFRESH_TOKEN": "your_refresh_token",
        "TICKTICK_CLIENT_ID": "your_client_id",
        "TICKTICK_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Cursor IDE

Add this server to your Cursor MCP configuration:

Location: Create/edit .cursorrules or Cursor settings for MCP servers

{
  "mcp": {
    "servers": {
      "ticktick": {
        "command": "node",
        "args": [
          "/path/to/ticktick-mcp-server/dist/index.js"
        ],
        "env": {
          "TICKTICK_ACCESS_TOKEN": "your_oauth_token",
          "TICKTICK_REFRESH_TOKEN": "your_refresh_token",
          "TICKTICK_CLIENT_ID": "your_client_id",
          "TICKTICK_CLIENT_SECRET": "your_client_secret"
        }
      }
    }
  }
}

Alternative with Username/Password

{
  "env": {
    "TICKTICK_USERNAME": "your_username",
    "TICKTICK_PASSWORD": "your_password"
  }
}

License

MIT