TickTick

You can run a TickTick MCP Server to seamlessly integrate TickTick task management with your MCP-enabled clients. This server exposes tasks, projects, and related actions, while handling timezone nuances and providing practical authentication options so you can automate workflows across your tools.

How to use

You connect an MCP client to the TickTick MCP Server by running the local server process and pointing your client’s MCP configuration to it. The server offers a set of endpoints and local execution options so you can manage tasks, projects, and due dates from your preferred environment. Use the OAuth flow or username/password to authorize access to TickTick, then invoke the available actions from your client’s MCP interface to list, create, update, delete, and complete tasks, as well as fetch overdue or today’s tasks with proper timezone handling.

How to install

Prerequisites you need before you begin:

• Node.js installed on your machine.

• A supported MCP client to connect to the server.

Follow these steps to set up and run the TickTick MCP Server locally:

# 1. Install dependencies
npm install

# 2. Create environment configuration
cp .env.example .env

# 3. Configure authentication in .env (choose one):
# 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

# 4. Build the project
npm run build

# 5. Run in development mode (optional)
npm run dev

# 6. Run in production mode
npm start

Additional configuration and usage notes

Timezone handling is built in to address TickTick’s timezone inconsistencies. The server applies a D+1 adjustment to due dates and supports a configurable timezone offset for overdue tasks. By default, overdue tasks use a UTC+8 offset; adjust this value when calling the relevant endpoint to match your location.

MCP integration examples

You can run the TickTick MCP Server locally via a standard Node.js process. Examples below show how to reference the compiled server and provide authentication details through environment variables.

Configuration samples

json
{
  "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"
      }
    }
  }
}

Alternative local runtime (Cursor/Desktop clients)

If you are using Cursor Desktop or similar MCP clients with local execution, you can configure the server to run via a standard node process using the same entry point and environment variables.

Security and best practices

Keep your OAuth tokens and client credentials secure. Do not commit tokens to version control. If you rotate credentials, update the environment configuration and restart the server.

Troubleshooting tips

If the server does not start, verify that Node.js is installed, dependencies are installed, and that the environment file (.env) is correctly configured. Check that the path to dist/index.js is valid after building the project.

Notes

All actions, such as listing tasks, creating tasks, updating, deleting, completing tasks, and fetching overdue or today’s tasks, are available through MCP clients once the server is running and properly authenticated.

Tools and endpoints you can use

• get_tasks: Retrieve all tasks or tasks within a specific project with enhanced display.
• get_overdue_tasks: Fetch overdue tasks with a configurable timezone offset (default UTC+8).
• get_todays_tasks: Retrieve tasks due today with D+1 timezone adjustment.
• get_projects: List all TickTick projects.
• create_task: Create a new task with priority, tags, and due dates.
• update_task: Update an existing task.
• delete_task: Delete a task.
• complete_task: Mark a task as completed.
• get_task: Get details for a specific task by ID.

Available tools

• get_tasks
• get_overdue_tasks
• get_todays_tasks
• get_projects
• create_task
• update_task
• delete_task
• complete_task
• get_task

Available tools

get_tasks

Retrieve all tasks or tasks from a specific project with enhanced human-friendly display.

get_overdue_tasks

Get overdue tasks with timezone compensation using a configurable offset (default UTC+8).

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, and 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.