Ticktick Mcp

What is Ticktick Mcp?

Ticktick Mcp is an MCP server that enhances your TickTick workflow. Built upon the ticktick-py library, it provides improved filtering capabilities, allowing AI assistants and MCP-compatible applications (like Claude Desktop, VS Code Agent Mode, or mcp-use) to interact with your tasks with greater precision and power.

How to use Ticktick Mcp?

Register a TickTick OpenAPI application to obtain Client ID, Client Secret, and Redirect URI. Create a .env file (default location ~/.config/ticktick-mcp/.env) with your credentials and TickTick login details. On first run, complete an OAuth2 authentication flow by authorizing the app in your browser and pasting the redirect URL. Then configure your MCP client (e.g., Claude Desktop) using the provided JSON configuration with uvx pointing to the Git repository.

Key features of Ticktick Mcp

• Create, update, delete, complete, and move tasks.
• Create subtasks by linking existing tasks.
• Retrieve uncompleted tasks, tasks by ID, or completed tasks within a date range.
• Filter tasks by priority, project, tags, due dates, and more.
• Manage projects, tags, and project folders.
• Convert datetime strings to TickTick's required format.

Use cases of Ticktick Mcp

• A daily stand-up agent fetches today’s tasks from TickTick and helps break down a selected task into subtasks.
• An AI assistant creates, updates, or completes tasks based on natural language commands.
• A developer integrates TickTick task management into VS Code Agent Mode for workflow automation.
• Automate task organization across projects by moving tasks or filtering by criteria like priority and due date.

FAQ from Ticktick Mcp

What are the prerequisites for running Ticktick Mcp?

You need Python >= 3.10, a TickTick account, and API credentials (Client ID, Client Secret, Redirect URI) obtained from the TickTick OpenAPI Developer portal.

How do I set up authentication?

Create a .env file with your credentials. On first run, an OAuth2 flow opens a browser for authorization; you must paste the full redirect URL (which contains a code= parameter) back into the terminal. A .token-oauth file is then created to cache the token for ~6 months.

Where should the .env file be placed?

By default, the server looks for a .env file at ~/.config/ticktick-mcp/.env. You can specify a different directory using the --dotenv-dir command-line argument when running the server directly via Python.

Can I integrate Ticktick Mcp with AI assistants like Claude Desktop?

Yes, the server is designed for MCP-compatible applications. The README provides example configuration for MCP clients using uvx with the Git repository URL.

What task filtering capabilities does Ticktick Mcp provide?

The ticktick_filter_tasks tool allows filtering by status, project ID, tag label, priority, due date range, completion date range, and sorting by priority, with optional timezone handling.