TickTick MCP Server

A Model Context Protocol (MCP) server designed for seamless integration with TickTick's task management environment, allowing conversational control via Claude or any compatible MCP client.

Core Functionalities

• 📑 Aggregate and display all extant TickTick projects and to-do entries.
• ✍️ Instantiate new projects and to-do items using vernacular instructions.
• 🛠️ Modify attributes of extant tasks (e.g., title, descriptive content, scheduling, urgency level).
• ☑️ Designate tasks as fully accomplished.
• ❌ Eliminate tasks and entire projects.
• 🌐 Complete adherence to TickTick's publicly available API specifications.
• 🔗 Effortless connectivity with conversational AI platforms like Claude and other MCP consumers.

System Requirements

• Execution environment requires Python version 3.10 or newer.
• Utilization of uv, the high-performance Python dependency resolver and installer.
• An active TickTick subscription capable of granting API access.
• Necessary TickTick API authentication credentials (Client Identifier, Secret Key, and Access Token).

Deployment Instructions

1. Source Code Acquisition: bash git clone https://github.com/jacepark12/ticktick-mcp.git cd ticktick-mcp

2. Installation via uv: bash # Obtain and install uv if not already present curl -LsSf https://astral.sh/uv/install.sh | sh

# Provision a sandboxed Python environment uv venv

# Activate the dedicated environment # For Unix-like systems: source .venv/bin/activate # For Windows systems: .venv\Scripts\activate

# Install the package in editable mode uv pip install -e .

1. API Credential Authorization: bash uv run -m ticktick_mcp.cli auth

This command initiates the following sequence: - Prompts for your TickTick Client ID and Client Secret. - Automatically launches a web browser window for TickTick authorization. - Securely archives the resulting access tokens within a local .env configuration file.

1. Verification Test: bash uv run test_server.py

Execute this to confirm successful communication with the TickTick backend using your provided credentials.

TickTick Authorization Protocol

This service employs the OAuth2 authorization framework for secure communication with TickTick:

1. Application Registration: Register your integration within the TickTick Developer Center

   • Mandate the callback URI be set as http://localhost:8000/callback.
   • Record the assigned Client ID and Client Secret.

2. Initiate Auth Flow: bash uv run -m ticktick_mcp.cli auth

3. Input the required Client ID and Secret when prompted.

4. Authorization confirmation will redirect you via a browser prompt to grant necessary permissions.

5. Upon successful authorization, the requisite access tokens are persisted in the .env file.

The system manages token expiration and renewal automatically, eliminating the need for manual re-authentication unless the stored tokens are explicitly revoked or the .env file is removed.

Dida365 (China) Configuration

滴答清单 - Dida365, the localized iteration of TickTick, requires a slight adjustment for authentication:

1. Register your client via the Dida365 Developer Center.

   • Set the redirect URI to http://localhost:8000/callback.
   • Note the Client ID and Secret.

2. Augment your .env file with the following endpoint configurations: env TICKTICK_BASE_URL='https://api.dida365.com/open/v1' TICKTICK_AUTH_URL='https://dida365.com/oauth/authorize' TICKTICK_TOKEN_URL='https://dida365.com/oauth/token'

3. Proceed with the standard authentication procedure detailed above.

Integration with Claude Desktop Application

To deploy this server for use with the localized Claude client:

1. Download and install Claude for Desktop.
2. Modify your desktop configuration file:

macOS Path: bash nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows Path: bash notepad %APPDATA%\Claude\claude_desktop_config.json

1. Incorporate the TickTick MCP server definition, ensuring the use of absolute file paths:

{ "mcpServers": { "ticktick": { "command": "", "args": ["run", "--directory", "", "-m", "ticktick_mcp.cli", "run"] } } }

1. Relaunch the Claude Desktop application.

Connectivity is confirmed when the TickTick service tools become visible within Claude, typically indicated by the 🔨 (tools) icon.

Provided MCP Endpoints

Endpoint Name	Functionality	Required Inputs
get_projects	Retrieve a roster of all user projects	None
get_project	Fetch detailed information for one project	project_id
get_project_tasks	List all assigned tasks within a specified project	project_id
get_task	Retrieve particulars of a singular task	project_id, task_id
create_task	Provision a new to-do item	title, project_id, content (optional), start_date (optional), due_date (optional), priority (optional)
update_task	Modify attributes of an existing task	task_id, project_id, title (optional), content (optional), start_date (optional), due_date (optional), priority (optional)
complete_task	Mark an item as finished	project_id, task_id
delete_task	Erase a specific task	project_id, task_id
create_project	Establish a novel project container	name, color (optional), view_mode (optional)
delete_project	Decommission a project	project_id

Specialized Task Query Endpoints

Retrieval and Text Search

Endpoint Name	Functionality	Required Inputs
get_all_tasks	Fetch every task across all associated projects	None
get_tasks_by_priority	Filter tasks based on assigned urgency	priority_id (0: None, 1: Low, 3: Medium, 5: High)
search_tasks	Execute a text search across titles, descriptions, and subtasks	search_term

Temporal Query Functions

Endpoint Name	Functionality	Required Inputs
get_tasks_due_today	Report tasks with a deadline on the current calendar day	None
get_tasks_due_tomorrow	Report tasks due on the next calendar day	None
get_tasks_due_in_days	Retrieve tasks due in precisely N days	days (Integer: 0 implies today, 1 implies tomorrow, etc.)
get_tasks_due_this_week	List tasks due within the immediate 7-day horizon	None
get_overdue_tasks	Display all tasks whose deadlines have passed	None

GTD Methodology Integration

Endpoint Name	Functionality	Required Inputs
get_engaged_tasks	Retrieve tasks designated as 'Engaged' (high priority or past due)	None
get_next_tasks	Retrieve 'Next Actions' (medium priority or due the following day)	None
batch_create_tasks	Insert multiple to-do items simultaneously	tasks (A structured list of task objects)

Illustrative Prompts for Claude Interaction

Once the TickTick interface is operational within Claude, utilize these examples:

General Operations

• "Present a catalog of every existing TickTick organizational unit."
• "Establish a new item titled 'Finalize MCP server documentation' within my 'Professional' container, assigning it the highest urgency level."
• "Enumerate all pending activities associated with my 'Personal' project."
• "Mark the to-do entry 'Acquire necessary provisions' as finished."
• "Instantiate a new organizational unit named 'Holiday Excursion' and assign it a cyan aesthetic."
• "What is the nearest scheduled commitment in my TickTick queue?"

Specific Filtering Queries

• "Which items must I address before the close of business today?"
• "Display all tasks that are currently past their established deadline."
• "Show me all items scheduled for completion this week."
• "Execute a search for items related to 'Q4 review initiative'."
• "List all entries containing the keyword 'vendor' in either the title or description."
• "Provide a list of all tasks flagged with high priority status."

GTD Workflow Application

In alignment with David Allen's GTD principles, leverage 'Engaged' and 'Next' action retrieval:

• Engaged tasks encompass high urgency, today's deadlines, or overdue items.
• Next tasks cover medium urgency or deadlines falling on the subsequent day.
• Employ batch_create_tasks to decompose complex objectives into manageable sub-actions.

For instance:

• "Allocate time slots between 14:00 and 20:00 today using items sourced from my 'Engaged' list."
• "Guide me through my immediate priorities and help determine my focus areas for tomorrow."
• "Deconstruct this overarching goal into five distinct, executable steps."

Development Insight

Directory Structure Overview

ticktick-mcp/ ├── .env.template # Schema for required environment variables ├── README.md # Comprehensive project documentation ├── requirements.txt # List of Python dependencies ├── setup.py # Package metadata and build script ├── test_server.py # Script for verifying server connectivity └── ticktick_mcp/ # Core Python package ├── init.py # Package initialization file ├── authenticate.py # Utilities for OAuth handling ├── cli.py # Command Line Interface definitions └── src/ # Internal source modules ├── init.py # Module initialization ├── auth.py # OAuth 2.0 implementation logic ├── server.py # The core MCP server framework └── ticktick_client.py # Abstraction layer for TickTick API calls

OAuth 2.0 Protocol Walkthrough

The system implements a complete, automated OAuth 2.0 provisioning sequence for TickTick:

1. Initialization: The user supplies their unique TickTick API Client ID and Secret.
2. Browser Grant: The user is redirected to the TickTick authorization endpoint to approve permissions.
3. Code Capture: A temporary local web listener intercepts the authorization code returned via the callback URL.
4. Token Swapping: The captured code is exchanged server-side for long-lived Access and Refresh tokens.
5. Secure Persistence: These tokens are stored securely within the local .env file.
6. Automatic Renewal: The client proactively refreshes the access token prior to expiration, maintaining session continuity.

This mechanism abstracts the complexities of the OAuth flow away from the end-user.

Contribution Guidelines

We welcome external contributions! Please submit revisions via a Pull Request.

1. Fork the upstream repository.
2. Establish a dedicated feature branch (git checkout -b feature/new-enhancement).
3. Commit changes with descriptive messages (git commit -m 'Implement feature X').
4. Push the branch to your fork (git push origin feature/new-enhancement).
5. Submit a formal Pull Request against the main repository.

Legal Status

This software is distributed under the terms of the MIT License (refer to the LICENSE file for full details).

WIKIPEDIA: Enterprise management solutions encompass the complete suite of applications, procedural guidelines, analytical mechanisms, and operational frameworks leveraged by organizations to navigate dynamic market conditions, maintain competitive parity, and enhance overall operational efficacy. These tools span departmental functions—from initial strategic planning and process governance to data stewardship, personnel management, executive decision support, and operational auditing. Modern business tooling has experienced rapid augmentation in the last decade, driven by technological acceleration, creating a challenge in selecting the optimal solutions for specific corporate requirements. This selection process is increasingly shaped by imperatives such as cost minimization, revenue growth objectives, deep customer insight acquisition, and the precise delivery of required products/services. Consequently, managerial focus should shift toward adopting a strategic, adaptable posture regarding management tools, customizing them to organizational idiosyncrasies rather than blindly adopting 'off-the-shelf' solutions.

== Prominent Categories == Market surveys, such as the 2013 analysis by Bain & Company, reveal global adoption patterns for management tools, reflecting regional economic pressures and corporate priorities. Key high-ranking categories typically include:

• Strategic Roadmapping and Planning
• Client Relationship Management (CRM)
• Personnel Sentiment Assessment (Surveys)
• Competitive Benchmarking
• Performance Measurement (Balanced Scorecard)
• Core Competency Identification
• External Resource Allocation (Outsourcing)
• Organizational Transformation Programs (Change Management)
• Logistics and Procurement Oversight (SCM)
• Foundational Corporate Mission Definition
• Client/Market Segmentation Analysis
• Total Quality Improvement Systems

== Business Software Ecosystem == Software applications utilized by personnel to execute distinct corporate functions are broadly defined as business software. These systems are intended to elevate productivity metrics, provide quantifiable performance indicators, and ensure precision in diverse operational tasks. The evolution traces from foundational Management Information Systems (MIS) through to extensive Enterprise Resource Planning (ERP) suites, followed by the integration of CRM modules, culminating in the modern landscape of cloud-based business management platforms. Value realization from Information Technology investments is contingent upon two critical factors: the proficiency of the system implementation and the judicious selection and customization of the underlying tools.

== Specialized Tools for Smaller Entities (SMEs) == Tools tailored for Small and Medium-sized Enterprises (SMEs) are vital as they frequently offer cost-effective pathways to achieve significant operational efficiency gains and stabilize growth trajectories.