Ticktick MCP

🚀 TickTick MCP Service

A Model Context Protocol (MCP) server implementation for integrating with the TickTick task management tool, powered by Python and the MCP SDK.

🚀 Quick Start

This repository houses an implementation of the Model Context Protocol (MCP) server for TickTick. It offers a standardized approach for AI assistants and applications to interact with TickTick's task management features, supporting the following operations:

• Retrieve projects and tasks
• Create new projects and tasks
• Update task details
• Complete and delete tasks

Through this MCP, AI systems can function as task managers, assisting you in managing to - do lists and tasks in TickTick using natural language processing.

✨ Features

• Standardized Interaction: Enables AI and apps to interact with TickTick's task management features in a standard way.
• Comprehensive Operations: Supports getting, creating, updating, completing, and deleting tasks.
• Natural Language Management: Facilitates task management with natural language processing.

📦 Installation

Prerequisites

• Python 3.8+
• A TickTick account
• A TickTick API key (via OAuth)

Steps

1. Clone this repository

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

2. Install dependencies

   pip install -r requirements.txt
   

📚 Documentation

Obtaining a TickTick API Key

This MCP uses TickTick's OpenAPI scheme. You need to register an application through the TickTick developer portal:

1. Visit TickTick Development Documentation.
2. Click Manage Apps in the top - right corner and log in with your TickTick credentials.
3. Click the +App Name button to create a new application.
4. Enter a name for your application (the only required field).
5. After the application is created, you'll be able to see your Client ID and Client Secret.
6. For the OAuth Redirect URL, enter a URL to redirect to after authorization (e.g., http://127.0.0.1:8080).

Authorizing Your Application

After registering the application, use the ticktick - py library to obtain an access token:

from ticktick.oauth2 import OAuth2

# Replace with details obtained 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 the browser for authorization
# Follow the instructions in the terminal to complete authorization
auth_client.get_access_token()

After authorization is complete, the access token will be saved to the default .token - oauth file. You can extract the token as follows:

print(auth_client.token_info["access_token"])

Configuration

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

   TICKTICK_API_KEY=Your access token
   

Usage

Run the MCP server:

python main.py

This will start the MCP server on port 8000. You can interact with the server as follows.

Provided Tools

• tick.tick(): Returns a time string of the current time.
• time.travel(seconds): A time - travel function that moves the current time forward or backward by the specified number of seconds.

Example Interactions

1. Get the current time:

   $ python main.py tick.tick
   

2. Move the time forward by 60 seconds:

   $ python main.py time.travel 60
   

3. Get the current time again:

   $ python main.py tick.tick
   

Extensibility

To extend the MCP server, add new command - handling functions in server.py and register them in the main() function.

def new_command():
    # Implement new functionality here
    pass

if __name__ == "__main__":
    register_command("new_command", new_command)

Compatibility

This MCP server is designed to be compatible with any client that supports the same commands. To create custom commands, follow these steps:

1. Define a new function.
2. Register the function in server.py.

def custom_function():
    # Implement functionality
    pass

if __name__ == "__main__":
    register_command("custom_function", custom_function)

By following these steps, you can easily extend the functionality of the MCP server to meet your needs.