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

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

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

1. Clone this repository:

   git clone https://github.com/jacepark12/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:

   # 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

4. Test your configuration:

   uv run test_server.py

   This will verify that your TickTick credentials are working correctly.

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

1. Register your application at the TickTick Developer Center

   • Set the 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. Follow the prompts to enter your Client ID and Client Secret

4. A browser window will open for you to authorize the application with your TickTick account

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

1. Install Claude for Desktop

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, using 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

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

You can run the TickTick MCP server inside a Docker container using the SSE transport option:

1. Build the Docker image:

   docker build -t ticktick-mcp .

2. Run the container with SSE transport:

   docker run -p 3434:3434 -v $(pwd)/.env:/app/.env ticktick-mcp uv run -m ticktick_mcp.cli run --transport sse --host 0.0.0.0 --port 3434

3. Configure Claude to connect to the containerized server: Edit your Claude configuration file and add the following:

   {
      "mcpServers": {
         "ticktick": {
            "url": "http://localhost:3434"
         }
      }
   }

4. Authentication in Docker: You have two options for authentication in Docker:

   Option 1: Mount .env file from host Run the authentication process outside of Docker to create the .env file, then mount it:

   # On your host machine
   uv run -m ticktick_mcp.cli auth
   
   # Then run Docker with the .env file mounted
   docker run -p 3434:3434 -v $(pwd)/.env:/app/.env ticktick-mcp

   Option 2: Pass environment variables directly Pass the TickTick authentication tokens as environment variables:

   docker run -p 3434:3434 \
     -e TICKTICK_CLIENT_ID=your_client_id \
     -e TICKTICK_CLIENT_SECRET=your_client_secret \
     -e TICKTICK_ACCESS_TOKEN=your_access_token \
     -e TICKTICK_REFRESH_TOKEN=your_refresh_token \
     ghcr.io/egv/ticktick-mcp:latest

Option 1: With mounted .env file

services:
  ticktick-mcp:
    build: .
    ports:
      - "3434:3434"
    volumes:
      - ./.env:/app/.env
    command: uv run -m ticktick_mcp.cli run --transport sse --host 0.0.0.0 --port 3434

Option 2: With environment variables

services:
  ticktick-mcp:
    image: ghcr.io/egv/ticktick-mcp:latest
    ports:
      - "3434:3434"
    environment:
      - TICKTICK_CLIENT_ID=your_client_id
      - TICKTICK_CLIENT_SECRET=your_client_secret
      - TICKTICK_ACCESS_TOKEN=your_access_token
      - TICKTICK_REFRESH_TOKEN=your_refresh_token
    restart: unless-stopped

The Docker image is automatically built and published to GitHub Container Registry. You can use the pre-built image instead of building it yourself:

# Pull the latest image
docker pull ghcr.io/egv/ticktick-mcp:latest

# Run with SSE transport
docker run -p 3434:3434 -v $(pwd)/.env:/app/.env ghcr.io/egv/ticktick-mcp:latest

Or in your docker-compose.yml:

services:
  ticktick-mcp:
    image: ghcr.io/egv/ticktick-mcp:latest
    ports:
      - "3434:3434"
    volumes:
      - ./.env:/app/.env
    restart: unless-stopped

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

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

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

The project implements a complete OAuth 2.0 flow for TickTick:

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

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

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

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

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