📌Overview

Purpose: The TickTick MCP Server facilitates direct interaction with the TickTick task management system through natural language processing clients like Claude.

Overview: This server implements the Model Context Protocol (MCP) to allow users to manage their TickTick tasks and projects effectively. It leverages Python and integrates seamlessly with TickTick's API for robust task management.

Key Features:

• Task and Project Management: View, create, update, complete, and delete tasks and projects through natural language commands, enhancing user experience and productivity.

• API Integration: Full integration with TickTick's open API allows for a comprehensive set of actions on tasks and projects, ensuring real-time updates and functionality.

---

TickTick MCP Server

A Model Context Protocol (MCP) server for TickTick that enables interaction 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 (GitHub)
• TickTick account with API access
• TickTick API credentials (Client ID, Client Secret, Access Token)

Installation

1. Clone this repository:

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

2. 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 .
   

3. Authenticate with TickTick:

   uv run -m ticktick_mcp.cli auth
   

   This will prompt for your TickTick Client ID and Client Secret, open a browser for login, and save your access tokens to a .env file.

4. Test your configuration:

   uv run test_server.py
   

   This verifies that your TickTick credentials are working correctly.

Authentication with TickTick

The server uses OAuth2 for authentication. Steps:

1. Register your application at the TickTick Developer Center: https://developer.ticktick.com/manage

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

2. Run the authentication command:

   uv run -m ticktick_mcp.cli auth
   

3. Enter your Client ID and Client Secret when prompted.

4. Authorize the application in the browser.

5. Access tokens will be saved to .env.

Tokens refresh automatically; reauthentication is only required if access is revoked or .env deleted.

Usage with Claude for Desktop

1. Install Claude for Desktop from https://claude.ai/download

2. 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
     

3. Add the TickTick MCP server configuration with absolute paths:

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

4. Restart Claude for Desktop.

After connecting, you’ll see the TickTick MCP tools available in Claude, indicated by the 🔨 icon.

Available MCP Tools

Tool	Description	Parameters
get_projects	List all TickTick projects	None
get_project	Get details of a project	project_id
get_project_tasks	List tasks in a project	project_id
get_task	Get details of a task	project_id, task_id
create_task	Create a new task	title, project_id, optional: content, start_date, due_date, priority
update_task	Update a task	task_id, project_id, optional: title, content, start_date, due_date, priority
complete_task	Mark a task complete	project_id, task_id
delete_task	Delete a task	project_id, task_id
create_project	Create a new project	name, optional: color, view_mode
delete_project	Delete a project	project_id

Example Prompts for Claude

• 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?

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         # Server test script
└── ticktick_mcp/          # Main package
    ├── __init__.py        
    ├── authenticate.py    # OAuth authentication utility
    ├── cli.py             # Command-line interface
    └── src/               
        ├── __init__.py    
        ├── auth.py        # OAuth implementation
        ├── server.py      # MCP server implementation
        └── ticktick_client.py  # TickTick API client

Authentication Flow

The OAuth 2.0 flow includes:

1. User inputs TickTick API Client ID and Secret
2. Redirect to TickTick for authorization
3. Local server captures OAuth callback with code
4. Code exchanged for access and refresh tokens
5. Tokens stored securely in .env
6. Automatic token refresh on expiration

This provides a smooth authentication experience.

Contributing

Contributions are welcome! To contribute:

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

License

This project is licensed under the MIT License.