TickTick MCP v2

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

Project Purpose

Easy Authentication: Direct username/password authentication.
Rich API Functionality: The v2 interfaces easy to implement more complex features. For example, other v1 TickTick interface cannot even retrieve tasks from the Inbox.

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
🔐 Username/password authentication with local credential storage

Quick Start

Create a mcp.json file:

{
  "mcpServers": {
    "ticktick-mcp-v2": {
      "command": "uvx",
      "args": ["--from", "ticktick-mcp-v2", "ticktick-mcp", "run"],
      "env": {
        "TICKTICK_USERNAME": "your_username",
        "TICKTICK_PASSWORD": "your_password"
      }
    }
  }
}

Start Using

You can now interact with your TickTick tasks directly! Try asking:

"Show me all my TickTick projects"
"Create a task called 'Finish documentation' with high priority"
"What tasks do I have due today?"

Development Setup

Install and authenticate:

uvx --from ticktick-mcp-v2 ticktick-mcp auth

Test the connection:

uvx --from ticktick-mcp-v2 ticktick-mcp test

Run the server:

uvx --from ticktick-mcp-v2 ticktick-mcp run

Usage Examples

Using with other MCP clients

Any MCP-compatible client can connect using the configuration above.

Available MCP Tools

Tool	Description	Parameters
Authentication
`auth_status`	Check authentication status	None
Project Management
`get_projects`	List all projects	None
`get_project`	Get project details	`project_id`
`create_project`	Create new project	`name`, `color` (optional), `view_mode` (optional)
`delete_project`	Delete project	`project_id`
`get_project_tasks`	Get tasks in project	`project_id`, `include_completed` (optional)
Task Management
`get_tasks`	List all tasks	`include_completed` (optional)
`create_task`	Create new task	`title`, `project_id` (optional), `content` (optional), `start_date` (optional), `due_date` (optional), `priority` (optional)
`update_task`	Update task	`task_id`, `project_id` (optional), `title` (optional), `content` (optional), `start_date` (optional), `due_date` (optional), `priority` (optional)
`delete_task`	Delete task	`project_id`, `task_id`
`complete_task`	Mark task complete	`task_id`
Advanced Features
`search_tasks`	Search tasks	`query`
`get_tasks_by_priority`	Get tasks by priority	`priority` (0=None, 1=Low, 3=Medium, 5=High)
`get_tasks_due_today`	Get tasks due today	None
`get_overdue_tasks`	Get overdue tasks	None

Example Prompts

"Show me all my TickTick projects"
"Create a task called 'Finish documentation' with high priority"
"What tasks do I have due today?"
"Mark the task 'Buy groceries' as complete"
"Update task 'Meeting notes' with new due date tomorrow"

Acknowledgments

This project would not be possible without the excellent work of the following open source projects:

🎯 ticktick-py

Original Author: Michael Lazeroff
Fork Maintainer: yidianyiko

The core TickTick Python SDK that powers this MCP server. This unofficial API library provides comprehensive access to TickTick's functionality, enabling seamless integration with the TickTick task management platform.

🤝 Contributing

If you find this project useful, please consider:

🐛 Reporting issues or suggesting improvements
📖 Contributing

License

MIT License - see LICENSE file for details.

TickTick