TickTick MCP Server

A Model Context Protocol (MCP) server for TickTick that enables interacting with your TickTick task management system directly through Claude and other MCP clients.

Features

📋 View all your TickTick projects and tasks
✏️ Create new projects and tasks through natural language
🔄 Update existing task details (title, content, dates, priority)
✅ Mark tasks as complete
🗑️ Delete tasks and projects
🔄 Full integration with TickTick's open API
🔌 Seamless integration with Claude and other MCP clients

Prerequisites

Python 3.10 or higher
uv - Fast Python package installer and resolver
TickTick account with API access
TickTick API credentials (Client ID, Client Secret, Access Token)

Installation

Clone this repository:

git clone https://github.com/jacepark12/ticktick-mcp.git
cd ticktick-mcp

Install with uv:

# Install uv if you don't have it already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a virtual environment
uv venv

# Activate the virtual environment
# On macOS/Linux:
source .venv/bin/activate
# On Windows:
.venv\Scripts\activate

# Install the package
uv pip install -e .

Authenticate with TickTick:
```
# Run the authentication flow
uv run -m ticktick_mcp.cli auth
```
This will:
- Ask for your TickTick Client ID and Client Secret
- Open a browser window for you to log in to TickTick
- Automatically save your access tokens to a .env file
Test your configuration:
```
uv run test_server.py
```
This will verify that your TickTick credentials are working correctly.

Authentication with TickTick

This server uses OAuth2 to authenticate with TickTick. The setup process is straightforward:

Register your application at the TickTick Developer Center
- Set the redirect URI to http://localhost:8000/callback
- Note your Client ID and Client Secret
Run the authentication command:
```
uv run -m ticktick_mcp.cli auth
```
Follow the prompts to enter your Client ID and Client Secret
A browser window will open for you to authorize the application with your TickTick account
After authorizing, you'll be redirected back to the application, and your access tokens will be automatically saved to the .env file

The server handles token refresh automatically, so you won't need to reauthenticate unless you revoke access or delete your .env file.

Authentication with Dida365

滴答清单 - Dida365 is China version of TickTick, and the authentication process is similar to TickTick. Follow these steps to set up Dida365 authentication:

Register your application at the Dida365 Developer Center
- Set the redirect URI to http://localhost:8000/callback
- Note your Client ID and Client Secret

Add environment variables to your .env file:

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'

Follow the same authentication steps as for TickTick

Usage with Claude for Desktop

Install Claude for Desktop

Edit your Claude for Desktop configuration file:

macOS:

nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows:

notepad %APPDATA%\Claude\claude_desktop_config.json

Add the TickTick MCP server configuration, using absolute paths:

{
   "mcpServers": {
      "ticktick": {
         "command": "<absolute path to uv>",
         "args": ["run", "--directory", "<absolute path to ticktick-mcp directory>", "-m", "ticktick_mcp.cli", "run"]
      }
   }
}

Restart Claude for Desktop

Once connected, you'll see the TickTick MCP server tools available in Claude, indicated by the 🔨 (tools) icon.

Available MCP Tools

Tool	Description	Parameters
`get_projects`	List all your TickTick projects	None
`get_project`	Get details about a specific project	`project_id`
`get_project_tasks`	List all tasks in a project	`project_id`
`get_task`	Get details about a specific task	`project_id`, `task_id`
`create_task`	Create a new task	`title`, `project_id`, `content` (optional), `start_date` (optional), `due_date` (optional), `priority` (optional)
`update_task`	Update an existing task	`task_id`, `project_id`, `title` (optional), `content` (optional), `start_date` (optional), `due_date` (optional), `priority` (optional)
`complete_task`	Mark a task as complete	`project_id`, `task_id`
`delete_task`	Delete a task	`project_id`, `task_id`
`create_project`	Create a new project	`name`, `color` (optional), `view_mode` (optional)
`delete_project`	Delete a project	`project_id`

Task-specific MCP Tools

Task Retrieval & Search

Tool	Description	Parameters
`get_all_tasks`	Get all tasks from all projects	None
`get_tasks_by_priority`	Get tasks filtered by priority level	`priority_id` (0: None, 1: Low, 3: Medium, 5: High)
`search_tasks`	Search tasks by title, content, or subtasks	`search_term`

Date-Based Task Retrieval

Tool	Description	Parameters
`get_tasks_due_today`	Get all tasks due today	None
`get_tasks_due_tomorrow`	Get all tasks due tomorrow	None
`get_tasks_due_in_days`	Get tasks due in exactly X days	`days` (0 = today, 1 = tomorrow, etc.)
`get_tasks_due_this_week`	Get tasks due within the next 7 days	None
`get_overdue_tasks`	Get all overdue tasks	None

Getting Things Done (GTD) Framework

Tool	Description	Parameters
`get_engaged_tasks`	Get "engaged" tasks (high priority or overdue)	None
`get_next_tasks`	Get "next" tasks (medium priority or due tomorrow)	None
`batch_create_tasks`	Create multiple tasks at once	`tasks` (list of task dictionaries)

Example Prompts for Claude

Here are some example prompts to use with Claude after connecting the TickTick MCP server:

General

"Show me all my TickTick projects"
"Create a new task called 'Finish MCP server documentation' in my work project with high priority"
"List all tasks in my personal project"
"Mark the task 'Buy groceries' as complete"
"Create a new project called 'Vacation Planning' with a blue color"
"When is my next deadline in TickTick?"

Task Filtering Queries

"What tasks do I have due today?"
"Show me everything that's overdue"
"Show me all tasks due this week"
"Search for tasks about 'project alpha'"
"Show me all tasks with 'client' in the title or description"
"Show me all my high priority tasks"

GTD Workflow

Following David Allen's "Getting Things Done" framework, manage an Engaged and Next actions.

Engaged will retrieve tasks of high priority, due today or overdue.
Next will retrieve medium priority or due tomorrow.
Break down complex actions into smaller actions with batch_creation

For example:

"Time block the rest of my day from 2-8pm with items from my engaged list"
"Walk me through my next actions and help my identify what I should focus on tomorrow?"
"Break down this project into 5 smaller actionable tasks"

Development

Project Structure

ticktick-mcp/
├── .env.template          # Template for environment variables
├── README.md              # Project documentation
├── requirements.txt       # Project dependencies
├── setup.py               # Package setup file
├── test_server.py         # Test script for server configuration
└── ticktick_mcp/          # Main package
    ├── __init__.py        # Package initialization
    ├── authenticate.py    # OAuth authentication utility
    ├── cli.py             # Command-line interface
    └── src/               # Source code
        ├── __init__.py    # Module initialization
        ├── auth.py        # OAuth authentication implementation
        ├── server.py      # MCP server implementation
        └── ticktick_client.py  # TickTick API client

Authentication Flow

The project implements a complete OAuth 2.0 flow for TickTick:

Initial Setup: User provides their TickTick API Client ID and Secret
Browser Authorization: User is redirected to TickTick to grant access
Token Reception: A local server receives the OAuth callback with the authorization code
Token Exchange: The code is exchanged for access and refresh tokens
Token Storage: Tokens are securely stored in the local .env file
Token Refresh: The client automatically refreshes the access token when it expires

This simplifies the user experience by handling the entire OAuth flow programmatically.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

TickTick MCP Server

A Model Context Protocol (MCP) server for TickTick that enables interacting with your TickTick task management system directly through Claude and other MCP clients.

Features

📋 View all your TickTick projects and tasks
✏️ Create new projects and tasks through natural language
🔄 Update existing task details (title, content, dates, priority)
✅ Mark tasks as complete
🗑️ Delete tasks and projects
🔄 Full integration with TickTick's open API
🔌 Seamless integration with Claude and other MCP clients

Prerequisites

Python 3.10 or higher
uv - Fast Python package installer and resolver
TickTick account with API access
TickTick API credentials (Client ID, Client Secret, Access Token)

Installation

Clone this repository:

git clone https://github.com/jacepark12/ticktick-mcp.git
cd ticktick-mcp

Install with uv:

# Install uv if you don't have it already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a virtual environment
uv venv

# Activate the virtual environment
# On macOS/Linux:
source .venv/bin/activate
# On Windows:
.venv\Scripts\activate

# Install the package
uv pip install -e .

Authenticate with TickTick:
```
# Run the authentication flow
uv run -m ticktick_mcp.cli auth
```
This will:
- Ask for your TickTick Client ID and Client Secret
- Open a browser window for you to log in to TickTick
- Automatically save your access tokens to a .env file
Test your configuration:
```
uv run test_server.py
```
This will verify that your TickTick credentials are working correctly.

Authentication with TickTick

This server uses OAuth2 to authenticate with TickTick. The setup process is straightforward:

Register your application at the TickTick Developer Center
- Set the redirect URI to http://localhost:8000/callback
- Note your Client ID and Client Secret
Run the authentication command:
```
uv run -m ticktick_mcp.cli auth
```
Follow the prompts to enter your Client ID and Client Secret
A browser window will open for you to authorize the application with your TickTick account
After authorizing, you'll be redirected back to the application, and your access tokens will be automatically saved to the .env file

The server handles token refresh automatically, so you won't need to reauthenticate unless you revoke access or delete your .env file.

Authentication with Dida365

滴答清单 - Dida365 is China version of TickTick, and the authentication process is similar to TickTick. Follow these steps to set up Dida365 authentication:

Register your application at the Dida365 Developer Center
- Set the redirect URI to http://localhost:8000/callback
- Note your Client ID and Client Secret

Add environment variables to your .env file:

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'

Follow the same authentication steps as for TickTick

Usage with Claude for Desktop

Install Claude for Desktop

Edit your Claude for Desktop configuration file:

macOS:

nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows:

notepad %APPDATA%\Claude\claude_desktop_config.json

Add the TickTick MCP server configuration, using absolute paths:

{
   "mcpServers": {
      "ticktick": {
         "command": "<absolute path to uv>",
         "args": ["run", "--directory", "<absolute path to ticktick-mcp directory>", "-m", "ticktick_mcp.cli", "run"]
      }
   }
}

Restart Claude for Desktop

Once connected, you'll see the TickTick MCP server tools available in Claude, indicated by the 🔨 (tools) icon.

Available MCP Tools

Tool	Description	Parameters
`get_projects`	List all your TickTick projects	None
`get_project`	Get details about a specific project	`project_id`
`get_project_tasks`	List all tasks in a project	`project_id`
`get_task`	Get details about a specific task	`project_id`, `task_id`
`create_task`	Create a new task	`title`, `project_id`, `content` (optional), `start_date` (optional), `due_date` (optional), `priority` (optional)
`update_task`	Update an existing task	`task_id`, `project_id`, `title` (optional), `content` (optional), `start_date` (optional), `due_date` (optional), `priority` (optional)
`complete_task`	Mark a task as complete	`project_id`, `task_id`
`delete_task`	Delete a task	`project_id`, `task_id`
`create_project`	Create a new project	`name`, `color` (optional), `view_mode` (optional)
`delete_project`	Delete a project	`project_id`

Task-specific MCP Tools

Task Retrieval & Search

Tool	Description	Parameters
`get_all_tasks`	Get all tasks from all projects	None
`get_tasks_by_priority`	Get tasks filtered by priority level	`priority_id` (0: None, 1: Low, 3: Medium, 5: High)
`search_tasks`	Search tasks by title, content, or subtasks	`search_term`

Date-Based Task Retrieval

Tool	Description	Parameters
`get_tasks_due_today`	Get all tasks due today	None
`get_tasks_due_tomorrow`	Get all tasks due tomorrow	None
`get_tasks_due_in_days`	Get tasks due in exactly X days	`days` (0 = today, 1 = tomorrow, etc.)
`get_tasks_due_this_week`	Get tasks due within the next 7 days	None
`get_overdue_tasks`	Get all overdue tasks	None

Getting Things Done (GTD) Framework

Tool	Description	Parameters
`get_engaged_tasks`	Get "engaged" tasks (high priority or overdue)	None
`get_next_tasks`	Get "next" tasks (medium priority or due tomorrow)	None
`batch_create_tasks`	Create multiple tasks at once	`tasks` (list of task dictionaries)

Example Prompts for Claude

Here are some example prompts to use with Claude after connecting the TickTick MCP server:

General

"Show me all my TickTick projects"
"Create a new task called 'Finish MCP server documentation' in my work project with high priority"
"List all tasks in my personal project"
"Mark the task 'Buy groceries' as complete"
"Create a new project called 'Vacation Planning' with a blue color"
"When is my next deadline in TickTick?"

Task Filtering Queries

"What tasks do I have due today?"
"Show me everything that's overdue"
"Show me all tasks due this week"
"Search for tasks about 'project alpha'"
"Show me all tasks with 'client' in the title or description"
"Show me all my high priority tasks"

GTD Workflow

Following David Allen's "Getting Things Done" framework, manage an Engaged and Next actions.

Engaged will retrieve tasks of high priority, due today or overdue.
Next will retrieve medium priority or due tomorrow.
Break down complex actions into smaller actions with batch_creation

For example:

"Time block the rest of my day from 2-8pm with items from my engaged list"
"Walk me through my next actions and help my identify what I should focus on tomorrow?"
"Break down this project into 5 smaller actionable tasks"

Development

Project Structure

ticktick-mcp/
├── .env.template          # Template for environment variables
├── README.md              # Project documentation
├── requirements.txt       # Project dependencies
├── setup.py               # Package setup file
├── test_server.py         # Test script for server configuration
└── ticktick_mcp/          # Main package
    ├── __init__.py        # Package initialization
    ├── authenticate.py    # OAuth authentication utility
    ├── cli.py             # Command-line interface
    └── src/               # Source code
        ├── __init__.py    # Module initialization
        ├── auth.py        # OAuth authentication implementation
        ├── server.py      # MCP server implementation
        └── ticktick_client.py  # TickTick API client

Authentication Flow

The project implements a complete OAuth 2.0 flow for TickTick:

Initial Setup: User provides their TickTick API Client ID and Secret
Browser Authorization: User is redirected to TickTick to grant access
Token Reception: A local server receives the OAuth callback with the authorization code
Token Exchange: The code is exchanged for access and refresh tokens
Token Storage: Tokens are securely stored in the local .env file
Token Refresh: The client automatically refreshes the access token when it expires

This simplifies the user experience by handling the entire OAuth flow programmatically.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

ticktick-mcp-server

TickTick MCP Server

Features

Prerequisites

Installation

Authentication with TickTick

Authentication with Dida365

Usage with Claude for Desktop

Available MCP Tools

Task-specific MCP Tools

Task Retrieval & Search

Date-Based Task Retrieval

Getting Things Done (GTD) Framework

Example Prompts for Claude

General

Task Filtering Queries

GTD Workflow

Development

Project Structure

Authentication Flow

Contributing

License

TickTick MCP Server

Features

Prerequisites

Installation

Authentication with TickTick

Authentication with Dida365

Usage with Claude for Desktop

Available MCP Tools

Task-specific MCP Tools

Task Retrieval & Search

Date-Based Task Retrieval

Getting Things Done (GTD) Framework

Example Prompts for Claude

General

Task Filtering Queries

GTD Workflow

Development

Project Structure

Authentication Flow

Contributing

License