Overview

The TickTick MCP Server implements a Model Context Protocol (MCP) interface that exposes TickTick task operations as tools for intelligent agents and automation workflows. It acts as a bridge between conversational AI models and TickTick accounts, enabling context-aware task creation, updates, queries, and bulk operations without embedding TickTick credentials in your agent logic.

This server is useful for developers building assistants, chatbots, or automation pipelines that need to read or modify task data in TickTick. By packaging common task operations as discrete MCP tools (with typed inputs and outputs), the server makes it simple to integrate task automation into LLM-driven workflows while preserving clear boundaries between the model and the external system.

Features

Exposes TickTick operations as MCP-compatible tools for use by LLM agents
Authenticate with TickTick (email/password or token) and manage multiple accounts
Create, update, complete, delete, and search tasks and lists
Query task context (tags, due dates, priorities, reminders, recurrence)
Bulk operations and contextual filters for workflow automation
Simple HTTP API and local development tooling (CLI / Docker friendly)

Installation / Configuration

Clone the repository, install dependencies, and configure credentials. Adjust commands for your environment.

Clone and install

git clone https://github.com/alexarevalo9/ticktick-mcp-server.git
cd ticktick-mcp-server
npm install

Environment variables

Create a .env file (or use your environment manager). Typical variables:

[email protected]
TICKTICK_PASSWORD=your_password
TICKTICK_TOKEN=optional_token_if_available
MCP_PORT=8080
LOG_LEVEL=info

If you manage multiple TickTick accounts, you can run multiple server instances or supply account identifiers in requests.

Run locally

npm run build
npm start

Or run in development mode:

npm run dev

Docker

A Dockerfile is provided for containerized deployment:

# build
docker build -t ticktick-mcp-server .

# run
docker run -d \
  -e [email protected] \
  -e TICKTICK_PASSWORD=your_password \
  -p 8080:8080 \
  ticktick-mcp-server

Adjust port mapping and env vars for your deployment environment.

Available Tools

The server exposes a set of MCP tools representing common TickTick actions. Each tool provides a typed input schema and a JSON result payload suitable for LLM tool invocation patterns.

Tool summary:

Tool name	Purpose	Key parameters
list_lists	Fetch lists/projects	account_id, query, limit
list_tasks	Query tasks	list_id, tag, status, due_before, limit
create_task	Create a new task	list_id, title, due_date, priority, tags, reminder
update_task	Update task fields	task_id, title?, due_date?, priority?, tags?
complete_task	Mark as complete	task_id
delete_task	Delete a task	task_id
search_tasks	Full-text search	q, account_id, limit
create_recurring	Set recurrence	task_id, rrule
set_reminder	Add/modify reminder	task_id, reminder_time

Example: create_task JSON input

{
  "list_id": "abcd1234",
  "title": "Prepare weekly report",
  "due_date": "2026-04-15T09:00:00Z",
  "priority": 2,
  "tags": ["work", "report"],
  "reminder": "2026-04-15T08:30:00Z"
}

Example API Calls

Create a task via the MCP server (HTTP):

curl -X POST "http://localhost:8080/tools/create_task" \
  -H "Content-Type: application/json" \
  -d '{
    "list_id": "abcd1234",
    "title": "Call supplier",
    "due_date": "2026-04-12T14:00:00Z",
    "priority": 1
  }'

Search tasks:

curl "http://localhost:8080/tools/search_tasks?q=invoice&limit=10"

Responses are JSON objects with standardized fields (status, data, error) to simplify downstream processing.

Use Cases

Intelligent personal assistant: An LLM agent with access to this MCP server can create tasks from natural language (e.g., “Remind me to pay rent on the 1st”) and attach appropriate due dates, reminders, and tags.
Email-to-task automation: Automatically parse incoming emails and create tasks in TickTick using the agent to extract title, deadline, and priority.
Daily standup automation: Query tasks assigned to “today” and summarize outstanding items, automatically creating or reprioritizing tasks based on meeting notes.
Bulk cleanup: Run a script that finds tasks matching filters (e.g., completed > 30 days) and removes or archives them.
Workflow augmentation: Combine MCP tools with other connectors (calendar, Slack) so the agent synchronizes tasks, posts reminders, or updates project boards.

Getting Started with an LLM

Integrate the MCP server as a tool endpoint in your LLM orchestration layer (e.g., using the agent/tool pattern). Provide the server base URL and authenticate requests as needed. Use the tool schemas so the model chooses the correct operation and supplies typed inputs, reducing hallucination risk when modifying user data.

If you encounter issues, enable debug logging and verify TickTick credentials. Consult the repository for additional deployment options, rate limits, and advanced configuration (multi-account, token refresh strategies, and secure secret management).

TickTick MCP Server for Intelligent Task Automation