mcp-dida365

This MCP server provides an integration for TickTick / Dida365 tasks within the MCP (Model Context Protocol) ecosystem. It automatically handles OAuth authentication by launching a browser for you on first run or when tokens become invalid, saving tokens locally in a .token file with a typical validity of 180 days. The server can read and write tasks, including new capabilities like subtasks and task filters, and it also provides access to collection inbox tasks through a workaround described in the setup notes. You’ll interact with it via an MCP client (for example Claude Desktop, Cursor, or Copilot) by pointing the client’s MCP configuration at this server and supplying the main.py path via uv’s run-with-mcp workflow. The server exposes a TickTick-based API surface that your MCP client can request to manage projects, tasks, subtasks, and filters.

Prerequisites:

• Python and uv (via uvx) installed on your system
• Git installed
• Access to TickTick / Dida365 OAuth credentials (Client ID and Client Secret)

1. Clone the repository and install dependencies

git clone https://github.com/Xrondev/mcp-dida365
cd mcp-dida365
# Set up a Python environment (recommended)
python3 -m venv .venv
source .venv/bin/activate
# Install any required Python dependencies
pip install -r requirements.txt

2. Configure OAuth and environment variables

• Register an application on TickTick or Dida365 developer portal
• Set redirect URI to http://localhost:11365/callback
• Create a .env file (or edit the template) with TickTick credentials and port as documented

cp .env.template .env
vim .env  # edit credentials and settings

3. Run the MCP server via uvx

# First, ensure you can locate the main.py and your uvx binary
uvx run --with mcp /absolute/path/to/main.py

4. Configure your MCP client

• In your MCP client configuration, add a server entry pointing to the uvx workflow as shown in the repository README
• Ensure the environment variables are visible to the uv process (or rely on the .env file in your shell)

5. First run and authentication

• The server will open a browser for OAuth authentication on first start or when the token is invalid
• Complete the login flow; tokens will be saved to a .token file

6. Validate

• Verify that the MCP client can connect and perform task operations (read/write) and that subtasks/filters behave as expected

Tips and caveats:

• Port 11365 is used for the OAuth redirect; if you change it, update the callback URL accordingly in the TickTick/Dida365 developer portal.
• Tokens live for about 180 days; there is no refresh token support in some endpoints, so you may need to re-authenticate periodically.
• If you encounter 'Token invalid', delete the .token file and re-authenticate.
• Ensure you use absolute paths in MCP client configurations when pointing to main.py and the uv executable.
• If the browser cannot open automatically, check that the port is reachable and manually navigate to the authentication URL from logs.
• For issues with collection inbox access or advanced features (filters, repeats), check the repository’s issues and logs (mcp.log) for hints and updates.