Dida MCP Server

A Model Context Protocol (MCP) server for interacting with TickTick/Dida365 task management service. This server provides tools to manage tasks, projects, and tags through the TickTick API.

Overview

Dida MCP Server is built on the Model Context Protocol framework, enabling AI assistants to interact with your TickTick/Dida365 account. It provides a comprehensive set of tools for task and project management, allowing AI assistants to help organize your tasks according to GTD (Getting Things Done) principles.

Features

• Authentication: OAuth-based authentication with TickTick/Dida365 API
• Task Management: Create, read, update, delete, and move tasks
• Project Management: Create, read, update, and delete projects
• Batch Operations: Efficiently manage multiple tasks at once
• GTD Assistant: Built-in system prompt for GTD-based task organization
• Cached Data: Efficient caching of projects and tags data

Prerequisites

• Node.js (v16 or higher)
• npm (v7 or higher)
• TickTick/Dida365 account
• Client ID and Client Secret from Dida365 Developer Center (for OAuth authentication)

Installation

Option 1: Install from npm (Recommended)

# Install globally
npm install -g dida-mcp-server

# Or install locally in your project
npm install dida-mcp-server

Option 2: Install from source

# Clone the repository
git clone https://github.com/zhongwencool/dida-mcp-server.git
cd dida-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

Authentication

Before using the server, you need to authenticate with TickTick/Dida365. The server supports two authentication methods:

1. OAuth Authentication (V1 API): Uses the Dida365 Open API with OAuth tokens
2. Username/Password Authentication (V2 API): Uses the internal API with session tokens

Using get-access-token

The get-access-token script handles the authentication process for both API versions. To use it:

# If installed globally
dida-get-token

# If installed locally or from source
npm run get-token

The script will:

1. Prompt you for your TickTick/Dida365 username and password (for V2 API)
2. Prompt you for your Client ID and Client Secret ([for V1 API OAuth])
3. Start a local server on port 3000 to handle the OAuth callback
4. Open your browser to authorize the application
5. Exchange the authorization code for an access token
6. Store both tokens in the configuration file at ~/.dida-mcp-config.json
7. Display a success page with token information and MCP server configuration

Prerequisites for OAuth Authentication

To use OAuth authentication, you need to:

1. Register your application in the Dida365 Developer Center
2. Set your redirect URI to http://localhost:3000/oauth/callback
3. Obtain a Client ID and Client Secret

Configuration File

The authentication process creates a configuration file at ~/.dida-mcp-config.json with the following structure:

{
  "access_token": "your-v1-oauth-token",
  "refresh_token": "your-refresh-token",
  "expires_at": 1234567890000,
  "token_type": "bearer",
  "v2_access_token": "your-v2-session-token",
  "inboxId": "your-inbox-project-id"
}

This file is automatically detected and used by the server when it starts.

Usage

Starting the Server

# If installed globally
dida-mcp-server

# If installed locally or from source
npm start

The server will automatically attempt to authenticate using stored tokens and display the authentication status.

Connecting with an MCP Client

You can connect to the server using any MCP-compatible client. The server provides a configuration that can be added to your MCP client configuration:

{
  "mcpServers": {
    "dida": {
      "command": "dida-mcp-server"
    }
  }
}

Or if you installed it locally:

{
  "mcpServers": {
    "dida": {
      "command": "node",
      "args": [
        "/path/to/node_modules/dida-mcp-server/dist/index.js"
      ]
    }
  }
}

Available Tools

Authentication Tools

• check-auth-status: Check the current authentication status

Project Management Tools

• list-projects: Get all projects
• create-project: Create a new project
• update-project: Update an existing project
• delete-project: Delete a project
• refresh-project-cache: Manually refresh the project cache

Task Management Tools

• list-tasks: Get tasks from a project (defaults to inbox)
• create-task: Create a new task
• get-task: Get a specific task by ID
• update-task: Update a task
• batch-update-tasks: Update multiple tasks at once
• complete-task: Mark a task as completed
• delete-task: Delete a task
• batch-delete-tasks: Delete multiple tasks at once
• move-task: Move a task to a different project
• batch-move-tasks: Move multiple tasks to different projects

Data Query Tools

• list-cached-data: View cached projects and tags data

System Prompts

The server includes two built-in prompts:

1. GTD Assistant Prompt: A system prompt that provides guidance on using the tools to implement GTD methodology
2. Process Inbox Prompt: A user-level prompt that helps organize tasks in the inbox according to GTD principles

Development

Running in Development Mode

npm run dev

This will start the server in watch mode, automatically recompiling and restarting when changes are made.

Running Tests

npm test

Or to run tests in watch mode:

npm run test:watch

Project Structure

├── dist/              # Compiled JavaScript files
├── src/
│   ├── auth/           # Authentication-related code
│   ├── projects/       # Project management tools
│   ├── resources/      # Resource definitions (cached data)
│   ├── tasks/          # Task management tools
│   ├── types/          # TypeScript type definitions
│   ├── utils/          # Utility functions
│   ├── config.ts       # Configuration management
│   ├── get-access-token.ts  # Token acquisition script
│   ├── index.ts        # Main server entry point
│   └── systemPrompt.ts # GTD assistant system prompt
├── tests/              # Test files
├── package.json        # Project metadata and dependencies
├── LICENSE             # ISC License file
└── tsconfig.json      # TypeScript configuration

API Documentation

This project uses the Dida365 Open API. For more information, see the Dida365 Open API Documentation.

License

ISC

Publishing to NPM

To publish the package to NPM, follow these steps:

# Login to npm (if not already logged in)
npm login

# Build the project
npm run build

# Test the package
npm test

# Publish to npm
npm publish

To update the package:

1. Update the version in package.json
2. Run npm publish

Contributing

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

Acknowledgements

• Model Context Protocol for the MCP framework
• TickTick/Dida365 for the task management service