TickTick MCP Server

MCP Server for the TickTick API, enabling task management, project organization, habit tracking, and more.

Features

• ✅ Task Management: Create, read, update, and delete tasks with all available properties
• 📊 Project Management: Create, read, update, and delete projects with customizable views
• 📋 Subtask Support: Full support for managing subtasks within parent tasks
• 🔄 Complete Task Control: Set priorities, due dates, reminders, and recurring rules
• 🔐 OAuth Authentication: Full OAuth2 implementation for secure API access
• ⚠️ Comprehensive Error Handling: Clear error messages for common issues

Tools

1. `get_task_by_ids`

2. `create_task`

3. `update_task`

4. `complete_task`

5. `delete_task`

6. `get_user_projects`

7. `get_project_by_id`

8. `get_project_with_data`

9. `create_project`

10. `update_project`

11. `delete_project`

Schema References

• `TickTickTaskSchema`: Defines the structure for task objects including:

• `TickTickProjectSchema`: Defines the structure for project objects including:
  • Project identification and naming
  • Display settings (color, view mode)
  • Permissions and organization

Tasks Properties

When creating or updating tasks, you can include these properties:

• Priority Levels:
  • `0`: None
  • `1`: Low
  • `3`: Medium
  • `5`: High
• Status Values:
  • `0`: Normal (not completed)
  • `2`: Completed
• Reminder Format:
  • Example: `["TRIGGER:P0DT9H0M0S", "TRIGGER:PT0S"]`
  • Follows iCalendar TRIGGER format
• Recurring Rules (repeatFlag):
  • Example: `"RRULE:FREQ=DAILY;INTERVAL=1"`
  • Uses RFC 5545 recurrence rules
• Date Format:
  • ISO 8601 format: `"yyyy-MM-dd'T'HH:mm:ssZ"`
  • Example: `"2019-11-13T03:00:00+0000"`

Projects Properties

When creating or updating projects, you can use these properties:

• View Modes:
  • `"list"`: Standard list view
  • `"kanban"`: Kanban board view
  • `"timeline"`: Timeline view
• Project Kinds:
  • `"TASK"`: Task-oriented project
  • `"NOTE"`: Note-oriented project

Setup

OAuth Authentication

To enable OAuth authentication with TickTick, you'll need to register your app and obtain API credentials:

• Create an account on the TickTick Developer Portal
• Register a new application
• Set the OAuth redirect URL to: http://localhost:8000/callback
• Copy the generated Client ID (TICKTICK_CLIENT_ID) and Client Secret (TICKTICK_CLIENT_SECRET)

First-Time Authorization Flow

When using the TickTick MCP server for the first time:

1. You'll be prompted to authorize the application

2. A browser window will open with the TickTick login page

3. After login, you'll be asked to grant permissions

4. The access token will be displayed in the page

5. Copy this token and set it as the TICKTICK_ACCESS_TOKEN environment variable

Generate Access Token

When you need to generate a new access token (either for first-time setup or when the token expires), follow these steps:

1. Configure your credentials using one of these methods:

#### Option 1: .env file (Recommended)

Create a `.env` file in your project root:

TICKTICK_CLIENT_ID=""
   TICKTICK_CLIENT_SECRET=""

Then load it:

source .env

This method is recommended because:

#### Option 2: Terminal Environment Variables

Use single quotes if your credentials contain special characters. Note that these variables will only persist in your current terminal session:

export TICKTICK_CLIENT_ID=''
   export TICKTICK_CLIENT_SECRET=''

2. Run the authentication command:

If using the published package:

npx @alexarevalo.ai/mcp-server-ticktick ticktick-auth

If running the MCP server locally:

npm run start:auth

The process will:

3. Save the access token:

echo "TICKTICK_ACCESS_TOKEN=\"\"" >> .env
   source .env

> Security Tips:

>

> - Add `.env` to your `.gitignore` file

> - Never commit credentials to version control

> - Access tokens expire after 180 days - you'll need to regenerate them

Usage with Claude Desktop

To use this with Claude Desktop, add the following to your `claude_desktop_config.json`:

NPX

{
  "mcpServers": {
    "ticktick": {
      "command": "npx",
      "args": ["-y", "@alexarevalo.ai/mcp-server-ticktick"],
      "env": {
        "TICKTICK_CLIENT_ID": "",
        "TICKTICK_CLIENT_SECRET": "",
        "TICKTICK_ACCESS_TOKEN": ""
      }
    }
  }
}

Docker

{
  "mcpServers": {
    "ticktick": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TICKTICK_CLIENT_ID",
        "-e",
        "TICKTICK_CLIENT_SECRET",
        "-e",
        "TICKTICK_ACCESS_TOKEN",
        "mcp/ticktick"
      ],
      "env": {
        "TICKTICK_CLIENT_ID": "",
        "TICKTICK_CLIENT_SECRET": "",
        "TICKTICK_ACCESS_TOKEN": ""
      }
    }
  }
}

Installing via Smithery

To install ticktick-mcp-server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @alexarevalo9/ticktick-mcp-server --client claude

Build

Docker build:

docker build -t mcp/ticktick -f src/ticktick/Dockerfile .

License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.