A powerful Model Context Protocol (MCP) server that enables seamless integration between Claude Desktop and TickTick task management system.

• 🌍 Smart Timezone Support - Automatic timezone detection with manual override options
• ⚡ Batch Operations - Create/update multiple tasks simultaneously
• 🔍 Advanced Search - Find tasks by title, content, or project with filters
• 📊 Analytics & Insights - Project statistics, overdue tracking, productivity metrics
• 📅 Smart Scheduling - Get today's tasks, upcoming deadlines, overdue items

• Full CRUD Operations - Create, read, update, delete tasks and projects
• Priority Management - Set and modify task priorities (None, Low, Medium, High)
• Date & Time Handling - Start dates, due dates with timezone awareness
• Project Organization - Manage multiple projects with different view modes
• Task Completion - Mark tasks as complete with automatic timestamps

• Natural Language Commands - Control TickTick through conversational Claude interface
• Real-time Synchronization - Changes reflect immediately in TickTick apps
• OAuth2 Authentication - Secure, token-based authentication with auto-refresh
• Error Handling - Robust error recovery and user-friendly messages

• Python 3.10+
• uv - Fast Python package manager
• Claude Desktop
• TickTick Account with API access

1. Clone the repository

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

2. Create and activate virtual environment

   uv venv
   # On Windows:
   .venv\Scripts\activate
   # On macOS/Linux:
   source .venv/bin/activate

3. Install dependencies

   uv pip install -e .
   uv pip install tzdata  # For timezone support

4. Set up TickTick API credentials

   Register your application at TickTick Developer Center:

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

5. Authenticate with TickTick

   uv run -m ticktick_mcp.cli auth

   This will:

   • Prompt for your Client ID and Client Secret
   • Open browser for TickTick authorization
   • Automatically save tokens to .env file

6. Test the setup

   uv run test_server.py

1. Find uv path

   # Windows
   where uv
   # macOS/Linux  
   which uv

2. Edit Claude Desktop config

   macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   Windows: %APPDATA%\Claude\claude_desktop_config.json

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

3. Restart Claude Desktop

"Show me all my TickTick projects"
"Create a task 'Buy groceries' in my Personal project"
"List all tasks in my Work project"
"Mark task 'Complete report' as done"

"Create 5 tasks for my morning routine in Personal project"
"Show me all overdue tasks"
"Find all tasks containing 'meeting'"
"What tasks do I have due today?"
"Show statistics for my Work project"
"Get upcoming tasks for next 7 days"

"Create multiple tasks: 'Review code', 'Write tests', 'Deploy to staging' all in Development project"
"Update all overdue tasks to be due tomorrow with high priority"

"Show project statistics for Work"
"Which tasks are overdue across all projects?"
"What's my completion rate this month?"
"Show me upcoming deadlines for next week"

Set your timezone in .env file:

TICKTICK_USER_TIMEZONE=America/New_York  # Eastern Time
TICKTICK_USER_TIMEZONE=Europe/London     # GMT
TICKTICK_USER_TIMEZONE=Asia/Tokyo        # JST

Auto-detection: If not set, the system will attempt to detect your timezone automatically.

For users of Dida365 (Chinese version of TickTick):

1. Register at Dida365 Developer Center
2. Add 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

cd ticktick-mcp
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
uv run -m ticktick_mcp.cli auth

uv pip install tzdata

cd ticktick-mcp
uv venv
.venv\Scripts\activate  # Windows
# or
source .venv/bin/activate  # macOS/Linux
uv pip install -e .

ticktick-mcp/
├── .env.template           # Environment variables template
├── README.md              # This file
├── requirements.txt       # Python dependencies
├── setup.py              # Package setup
├── test_server.py         # Connection test script
└── ticktick_mcp/          # Main package
    ├── __init__.py
    ├── authenticate.py    # OAuth authentication utility
    ├── cli.py            # Command-line interface
    └── src/              # Source code
        ├── __init__.py
        ├── auth.py       # OAuth implementation
        ├── server.py     # MCP server implementation
        └── ticktick_client.py  # TickTick API client

• 🌍 Enhanced Timezone Support - Smart detection + manual override
• ⚡ Batch Operations - Process multiple tasks simultaneously
• 🔍 Advanced Search - Find tasks across projects with filters
• 📊 Analytics Dashboard - Project statistics and productivity insights
• 📅 Smart Scheduling - Today's tasks, upcoming deadlines, overdue tracking
• 🔄 Improved Error Handling - Better user feedback and recovery
• 🚀 Performance Optimizations - Faster task processing and API calls

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

• Model Context Protocol for the amazing protocol
• TickTick for the robust API
• Claude for the powerful AI integration
• All contributors and users who made this project better