jen6/ticktick-mcp

Enhance your TickTick workflow with this MCP server. Built upon the ticktick-py library, it offers significantly 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.
✨ Features
This server provides comprehensive access to TickTick functionalities via MCP tools, categorized as follows:
* **Task Management:** Create, update (including conversion to TickTick's date format), delete, complete, and move tasks.
* **Subtask Management:** Create subtasks by linking existing tasks.
* **Task Retrieval:**
* Get all uncompleted tasks.
* Get tasks by ID or specific fields.
* Get completed tasks within a date range.
* Get tasks from a specific project.
* Filter tasks based on various critggeria (priority, project, tags, etc.).
* **Project/Tag Management:** Retrieve all projects, tags, and project folders.
* **Helper Tools:** Convert datetime strings to the required TickTick format.
Refer to the tool definitions within the src/ticktick_mcp/tools/ directory for detailed specifications.
🚀 Getting Started
This server utilizes the unofficial ticktick-py library to interact with the TickTick API.
Prerequisites
* Python >= 3.10
* Access to TickTick and API credentials (see below).
Setup
1. **Register a TickTick Application:** Before using the server, you need to register an application with TickTick to obtain API credentials. Follow these steps based on the ticktick-py documentation:
* Go to the TickTick OpenAPI Documentation and log in with your TickTick account.
* Click on Manage Apps in the top right corner.
* Register a new app by clicking the +App Name button. Provide a name for your application (e.g., "MCP Server").
* Once created, edit the app details. Note down the generated Client ID and Client Secret.
* For the OAuth Redirect URL, enter a URL where you want to be redirected after authorizing the application. It doesn't need to be a live URL
* http://localhost:8080/redirect or http://127.0.0.1:8080/ are common choices for local development.
* **Ensure this exact URL is saved in your environment variables.**
2. **Environment Variables:** The server requires the TickTick API credentials you just obtained, plus your TickTick login details. By default, it looks for a .env file located at ~/.config/ticktick-mcp/.env.
* The server *might* create the ~/.config/ticktick-mcp/ directory if it doesn't exist, but it's safer to create it manually.
* You **must create the .env file manually** within that directory.
* Alternatively, you can specify a different directory using the --dotenv-dir command-line argument *only* when running the server directly via Python (see "Running the Server" below).
The .env file should contain:
3. **Authentication (First Run):** On the first run (either directly or via an MCP client), the underlying ticktick-py library will initiate an OAuth2 authentication flow.
* A web browser window might open automatically, or a URL will be printed in the console/log output.
* You need to visit this URL, log in to TickTick if necessary, and authorize the application (granting Read and Write permissions).
* After authorization, you will be redirected to the TICKTICK_REDIRECT_URI you specified.
* The console will prompt you to **paste this full redirected URL** (which includes a code= parameter) back into the terminal.
* Upon successful verification, a .token-oauth file will be created in the same directory as your .env file.