TickTick MCP Server exposes a set of tools that allow you to interact with TickTick task management directly from your MCP client. The server provides commands to list tasks and projects, create, update, delete, and complete tasks, and fetch specific task details. It also includes handy time zone handling features to compensate TickTick's quirks, such as a D+1 adjustment for due dates and a configurable time zone offset when retrieving overdue tasks. Typical usage involves connecting via a Node-based MCP client configuration (as shown in the README examples) and invoking the available tools like get_tasks, get_projects, create_task, update_task, delete_task, complete_task, get_task, get_overdue_tasks, and get_todays_tasks. OAuth-based authentication is supported (recommended) and can fall back to username/password authentication if needed. The tools return enriched task data with human-readable priority text and enhanced display for easier viewing in MCP clients.

Prerequisites:

• Node.js (recommended version compatible with the project) and npm installed
• Access to TickTick credentials (OAuth tokens or username/password)

Installation steps:

1. Clone the repository or obtain the MCP server package: git clone https://github.com/rafliruslan-ticktick-mcp-server.git cd rafliruslan-ticktick-mcp-server

2. Install dependencies: npm install

3. Create and configure environment variables: cp .env.example .env

   edit .env to provide either OAuth tokens (recommended) or username/password

4. Build the project (if applicable): npm run build

5. Start the server (development): npm run dev

6. Start the server (production): npm start

Note: The MCP server is designed to be run with Node.js and the built dist/index.js entry point. If your build outputs to a different path, adjust the mcp_config accordingly.

Tips and known considerations:

• Timezone handling is customized to compensate TickTick inconsistencies. Be sure to use the configured timezone offset when calling get_overdue_tasks to get accurate results for your locale.
• The D+1 adjustment is applied to due dates to align with TickTick's timezone behavior; understand this when displaying or calculating deadlines.
• When using OAuth, ensure your TICKTICK_CLIENT_ID and TICKTICK_CLIENT_SECRET are kept secure and never exposed in client configurations.
• If you switch to username/password authentication, ensure the credentials are provided securely in the environment and that the TickTick account supports this method.
• Build artifacts (dist/index.js) must be reachable by the MCP client; adjust the mcp_config path if your deployment structure differs.
• For production deployments, consider packaging and running via a process manager (e.g., PM2) and ensure proper environment variable management.
• If you encounter rate limits or authentication errors, refresh tokens as needed and verify that the OAuth scopes include the necessary TickTick permissions.