ekkyarmandi/ticktick-mcp

A Model Context Protocol (MCP) server that provides tools for integrating TickTick task management tools. Using Python and the MCP SDK.

Overview

This repository contains a Model Context Protocol (MCP) server implementation for TickTick. It provides a standardized way for AI assistants and applications to interact with TickTick's task management functionality, allowing operations like:

• Retrieving projects and tasks
• Creating new projects and tasks
• Updating task details
• Completing and deleting tasks

With this MCP, AI systems can act as task masters to help manage your to-do lists and tasks in TickTick with natural language.

Requirements

• Python 3.8+
• TickTick account
• TickTick API key (via OAuth) # COMMENT: I will add a tool to generate an API key from the TickTick developer portal

Installation

1. Clone this repository

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

2. Install dependencies

   pip install -r requirements.txt
   

Obtaining a TickTick API Key

This MCP uses TickTick's OpenAPI scheme, which requires registering an app through TickTick's developer portal:

1. Go to the TickTick Developer Documentation
2. Click on Manage Apps in the top right corner and login with your TickTick credentials
3. Register a new app by clicking the +App Name button
4. Enter a name for your app (only required field)
5. Once created, you'll be able to see your Client ID and Client Secret
6. For the OAuth Redirect URL, enter a URL where you'll be redirected after authorization (e.g., http://127.0.0.1:8080)

Authorizing Your App

After registering your app, use the ticktick-py library to get your access token:

from ticktick.oauth2 import OAuth2

# Replace with your details from the developer portal
client_id = "YOUR_CLIENT_ID"
client_secret = "YOUR_CLIENT_SECRET"
redirect_uri = "YOUR_REDIRECT_URI"  # e.g., http://127.0.0.1:8080

auth_client = OAuth2(client_id=client_id,
                    client_secret=client_secret,
                    redirect_uri=redirect_uri)

# This will open a web browser for authorization
# Follow the instructions in the terminal to authorize
auth_client.get_access_token()

After authorizing, the access token will be saved to a .token-oauth file by default. You can extract the token from this file or use:

print(auth_client.token_info["access_token"])

Configuration

1. Create a .env file in the root directory with your TickTick API key:

   TICKTICK_API_KEY=your_access_token_here
   

Usage

Run the MCP server:

python main.py

This will start the MCP server on port 8000. You can now connect to it using any MCP client.

Available Tools

The server provides the following tools:

• get_projects: Get a list of all projects
• project_details: Get details of a specific project
• get_task_details: Get details of a specific task
• create_project: Create a new project
• create_task: Create a new task in a project
• update_task: Update an existing task
• complete_task: Mark a task as complete
• delete_task: Delete a task

Example Interactions

Once your MCP server is running, AI systems can help manage your tasks with natural language commands like:

• "Show me all my projects"
• "Create a new project called 'Home Renovation'"
• "Add a task to buy groceries tomorrow"
• "Mark my 'Pay bills' task as complete"
• "What tasks do I have due this week?"
• "Delete the task about the canceled meeting"

Using with MCP Clients

This server can be used with any MCP-compatible client, such as:

• Claude Desktop
• Cursor IDE
• Custom AI applications using MCP SDKs

Development

To extend or modify this MCP server:

1. Add new tools in tools.py
2. Register them in main.py using mcp.add_tool()

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.