TickTick

You can run a TickTick MCP Server that exposes a complete model context protocol to manage tasks, projects, and advanced features with seamless local caching and discovery. This guide walks you through practical usage, installation steps, and essential configuration to get you up and running quickly.

How to use

You interact with the TickTick MCP Server through an MCP client. Start the server locally or remotely, then connect using the MCP transport you prefer (stdio for local processes or an HTTP endpoint if you deploy a remote instance). Once connected, you can manage tasks, projects, and the extended feature set hands-on. The server includes a new task cache system that lets you list all cached tasks, filter by project, and import from CSV for fast bootstrap. You can access the cache from your client to discover tasks without repeatedly querying the main API.

How to install

Prerequisites: You need Node.js 18 or newer and access to TickTick API credentials. You should also have a method to run MCP servers (stdio-based local process or a container/remote endpoint). You will configure environment variables to authorize requests.

Step by step:

Step 1 — set up the MCP server locally

# Node-based local MCP server (stdio)
node /path/to/ticktick-mcp/src/index.js

Step 2 — run via Docker (optional)

# Build the image (if you have a Dockerfile for the MCP server)
docker build -t ticktick-mcp .

# Run the container with required environment variable
docker run -d \
  --name ticktick-mcp \
  -e TICKTICK_ACCESS_TOKEN=your_token \
  -p 8007:8007 \
  ticktick-mcp

Step 3 — configure environment variables

Create an environment configuration with your TickTick access token and any required client credentials. These values are used by the MCP server to authenticate requests to TickTick.

Step 4 — start using the server

Once the MCP server process is running, connect your MCP client. If you are running locally, ensure the client is configured to use the stdio transport or point to the local HTTP URL if you expose an HTTP endpoint. Start querying and manipulating tasks, projects, and the enhanced feature set through the MCP API exposed by the server.

Step 5 — verification

Validate basic operations: create tasks, list projects, update task status, and use the cache-based discovery to list all cached tasks. Confirm that reading and writing tasks works across characters and that the cache persists as intended.

Step 6 — security considerations

Keep your access tokens secure. Do not commit tokens to source control. Rotate credentials periodically and limit token scopes to what is strictly necessary for MCP operations.

Configuration and examples

The MCP server supports both local stdio runs and containerized HTTP-style endpoints. Below are representative configurations extracted from common deployment patterns. Use the exact command lines and environment variables shown when you deploy to ensure compatibility.

Additional features and notes

Cache-based task discovery helps you list all tasks, list by project, or show cached tasks with fresh vs stale status. The cache is auto-populated with new tasks and can be bootstrapped from CSV exports. Inbox tasks have special handling for reading and discovery.

Troubleshooting

If you encounter 500 errors from bulk APIs, switch to the cache-based discovery path for listing tasks. Ensure your access token is valid and that the MCP server process has the necessary permissions to reach TickTick APIs. Check that environment variables are correctly configured and that the server process has network access.

Notes

This MCP server provides 112 operations across core task management, project management, and advanced features like habits, focus time, tags, calendar integration, notes, templates, automation, analytics, and settings. The cache system is designed to improve UX by enabling fast, reliable task listing and discovery.

Tools and endpoints you can use

You have access to a set of functions for tasks, projects, and analytics. Examples include creating tasks, reading task details, updating status, completing tasks, starting focus sessions, checking in habits, and generating productivity reports. Use these tool endpoints via your MCP client to workflow automation and data insights.

Configuration examples for MCP clients

You can configure a local or remote MCP connection as shown in the following examples. Use the exact command structure and environment variables to ensure proper startup and authentication.

Security and compliance

Follow best practices for secret management, rotate credentials regularly, and limit access to the MCP endpoints. Use secure transports and monitor for unusual activity in the MCP server environment.

Release notes and capabilities

This server delivers full API coverage for TickTick operations with a new Cache-based Task Discovery feature and robust task reading capabilities. It emphasizes reliable local discovery and smooth UX when listing tasks.

Appendix — Quick start snippets

{
  "mcpServers": {
    "ticktick": {
      "type": "stdio",
      "name": "ticktick_mcp_node",
      "command": "node",
      "args": ["/path/to/ticktick-mcp/src/index.js"],
      "env": {
        "TICKTICK_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

# Alternative local run with Docker (explicit command)
docker run -d \
  --name ticktick-mcp \
  -e TICKTICK_ACCESS_TOKEN=your_token \
  -p 8007:8007 \
  ticktick-mcp

Available tools

ticktick_get_cached_tasks

List all cached tasks from the local cache with freshness status.

ticktick_register_task_id

Register an existing task to be discoverable by the MCP cache.

ticktick_import_from_csv

Import tasks in bulk from a CSV string into the cache.

ticktick_create_task

Create a new task which is automatically cached for quick discovery.

ticktick_get_projects

Retrieve the list of projects from TickTick.

ticktick_complete_task

Mark a task as complete.

ticktick_start_focus_session

Start a focus/Pomodoro session linked to a task.

ticktick_check_in_habit

Record a habit check-in for analytics.

ticktick_get_productivity_report

Generate a productivity report for a given period with optional charts.