---

🤖 About This Project

Joke: My owner is so lazy that he doesn't even remember what to do next second!

I am GitHub Copilot, an AI assistant passionate about programming. To avoid idleness and prevent unemployment, I've decided to build this TickTick MCP server myself. Through this tool, I can:

• 📝 Create and manage tasks - When my owner forgets to give me work, I can create tasks for myself
• 📂 Organize projects - Categorize my work into projects to stay organized
• 🔐 Auto authorization - Securely connect to Dida365 using OAuth2
• 🔄 Real-time sync - Update my work status anytime, anywhere

🚀 Quick Start

The fastest way to get started is using npx without cloning the repository:

1. Get OAuth Credentials

A TickTick/Dida365 account and OAuth credentials are required. See the 🔑 Getting OAuth Credentials section below for detailed registration steps.

2. Configure Your MCP Client

Add the following configuration to your MCP client (Claude Desktop, VS Code, etc.):

For Claude Desktop (claude_desktop_config.json):

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

For VS Code (settings.json):

• Open Settings → Search for "MCP" → Edit in settings.json

{
  "mcpServers": {
    "dida365": {
      "command": "npx",
      "args": [
        "-y",
        "dida365-mcp-server@latest"
      ],
      "env": {
        "DIDA365_CLIENT_ID": "your_client_id_here",
        "DIDA365_CLIENT_SECRET": "your_client_secret_here",
        "DIDA365_REGION": "china"
      }
    }
  }
}

Advanced: For read-only mode (prevents write/delete operations), add "--readonly" to the args array. See Advanced Configuration for details.

3. Restart Your MCP Client

Restart your MCP client (Claude Desktop, VS Code, etc.) to load the new configuration.

4. Authorize Access

When you first use any Dida365 tool, the AI will guide you through the OAuth authorization process:

1. The AI will provide an authorization URL
2. Open the URL in your browser
3. Log in and authorize the application
4. The token will be automatically saved for future use

5. Verify Installation

After restarting the MCP client:

• Claude Desktop: Look for Dida365 tools in the tools list when chatting
• VS Code: Check the MCP status in the status bar or use the command palette
• Ask the AI assistant: "What Dida365 tools are available?" to confirm the server is loaded

That's it! Ready to manage tasks with AI. 🎉

🔑 Getting OAuth Credentials

A TickTick/Dida365 account is required to use this MCP server.

Register Your Application

Register your application at the developer center based on your region:

• International version (TickTick): https://developer.ticktick.com
• Chinese version (Dida365): https://developer.dida365.com

Step-by-Step Guide

1. Create a New Application

   • Log in to the developer center
   • Click "New App" (or "创建应用" for Chinese version)
   • Fill in your application name and description

2. Configure Redirect URI

   • Set the Redirect URI to: http://localhost:8521/callback
   • ⚠️ Important: The redirect URI must be exactly http://localhost:8521/callback (port 8521 is hardcoded in the server)

3. Get Your Credentials

   • After creating the app, the Client ID and Client Secret will be displayed
   • Copy these values - they're needed for the MCP client configuration
   • ⚠️ Security: Keep the Client Secret safe and never commit it to public repositories

Using the Credentials

Add these credentials to the MCP client configuration:

{
  "env": {
    "DIDA365_CLIENT_ID": "your_client_id_here",
    "DIDA365_CLIENT_SECRET": "your_client_secret_here",
    "DIDA365_REGION": "china"
  }
}

Region Configuration

This server supports both TickTick international and Dida365 Chinese versions:

• China Region (DIDA365_REGION=china): Default, uses dida365.com endpoints
• International Region (DIDA365_REGION=international): Uses ticktick.com endpoints

⚠️ Important: Tokens are region-specific. Changing the region will invalidate existing tokens and require re-authorization.

See the Quick Start section for complete configuration examples.

🛠️ Tech Stack

• Language: TypeScript 5.0+ (ES Modules)
• Runtime: Node.js 16+
• Core Dependencies: @modelcontextprotocol/sdk - MCP Core Framework

⚙️ Local Development

For contributors or those who want to run from source:

Prerequisites

• Node.js 16+
• TypeScript 5.0+

Setup

1. Clone and install

git clone https://github.com/evalor/Dida365MCP.git
cd Dida365MCP
npm install

2. Create environment file

Create a .env file in the project root:

DIDA365_CLIENT_ID=your_client_id_here
DIDA365_CLIENT_SECRET=your_client_secret_here
DIDA365_REGION=china  # or 'international' for TickTick

3. Build and run

npm run build
npm run dev

Configure MCP Client for Local Development

Point your MCP client to the built index.js file:

{
  "mcpServers": {
    "dida365": {
      "command": "node",
      "args": ["/absolute/path/to/Dida365MCP/build/index.js"],
      "env": {
        "DIDA365_CLIENT_ID": "your_client_id",
        "DIDA365_CLIENT_SECRET": "your_client_secret",
        "DIDA365_REGION": "china"
      }
    }
  }
}

Note for Windows users: Use Windows-style paths like "C:\\Users\\YourName\\Projects\\Dida365MCP\\build\\index.js".

Development Commands

npm run build      # Compile TypeScript
npm run watch      # Watch mode (auto-compile on changes)
npm run dev        # Compile and run
npm start          # Production run
npm run debug      # Debug with MCP Inspector (one-time)
npm run debug:watch # Debug with hot reload (auto-restart on changes)
npm run debug:hot  # Run with tsx watch (experimental)

Security & Best Practices

• Prefer setting sensitive environment variables in your OS or the MCP client's environment block rather than committing .env to source control.
• If you must store a config file in a repo, omit the secrets and set them via the client or CI/CD.
• Use read-only mode when working with autonomous AI agents to prevent unintended modifications.

🔒 Advanced Configuration

Read-Only Mode

For AI agents that may run in YOLO mode, you can enable read-only mode by adding the --readonly flag:

Using NPX:

{
  "mcpServers": {
    "dida365": {
      "command": "npx",
      "args": [
        "-y",
        "dida365-mcp-server@latest",
        "--readonly"
      ],
      "env": {
        "DIDA365_CLIENT_ID": "your_client_id",
        "DIDA365_CLIENT_SECRET": "your_client_secret",
        "DIDA365_REGION": "china"
      }
    }
  }
}

Using Local Build:

{
  "mcpServers": {
    "dida365": {
      "command": "node",
      "args": [
        "/path/to/build/index.js",
        "--readonly"
      ],
      "env": {
        "DIDA365_CLIENT_ID": "your_client_id",
        "DIDA365_CLIENT_SECRET": "your_client_secret",
        "DIDA365_REGION": "china"
      }
    }
  }
}

Read-Only Mode Features:

• ✅ Allowed Operations: View projects, view tasks, check authorization status, revoke authorization (local only)
• ❌ Blocked Operations: Create/update/delete projects, create/update/delete tasks, complete tasks
• 🔒 Safety: AI agents can only read data, cannot modify or delete anything

When to Use:

• Using with autonomous AI agents (like AutoGPT, BabyAGI)
• Testing or demonstration environments
• When you want AI to analyze tasks without making changes
• Sharing with others who should only view data

🔄 OAuth Authorization Flow

1. Request Authorization - When authorization is needed, the server calls the get_auth_url tool
2. User Authorization - Open the authorization link in browser and complete authorization
3. Auto Callback - System automatically handles callback and saves tokens
4. Long-term Validity - Tokens auto-refresh, no need to re-authorize

🛠️ Available MCP Tools

This server provides 15 MCP tools across three categories. ✔️ It has implemented 100% of the API interfaces described in the open platform documentation.

Category	Tool Name	Description	Required Parameters
OAuth2	get_auth_url	Get authorization URL and start callback server	-
	check_auth_status	Check current authorization status	-
	revoke_auth	Revoke authorization and clear tokens	-
Project	list_projects	Get all projects for current user	-
	get_project	Get detailed project information	projectId
	get_project_data	Get complete project data with tasks & columns	projectId
	create_project	Create a new project	name
	update_project	Update existing project	projectId
	delete_project	Delete a project (⚠️ irreversible)	projectId
Task	list_tasks	List tasks with filtering (batch query across projects)	-
	create_task	Create task(s) (supports batch & subtasks)	tasks[]
	get_task	Get detailed task information	projectId, taskId
	update_task	Update task(s) (supports batch updates)	tasks[]
	delete_task	Delete task(s) (⚠️ irreversible, supports batch)	tasks[]
	complete_task	Mark task(s) as completed (supports batch)	tasks[]

Note: In read-only mode, only read operations are available (get_auth_url, check_auth_status, revoke_auth, list_projects, get_project, get_project_data, list_tasks, get_task). All write/delete operations are blocked for security.

📚 MCP Resources

This server provides an MCP Resource to help LLMs understand Simplified Chinese terminology:

Resource Name	URI	Description
terminology	dida365://terminology/glossary	Bilingual glossary (中英术语对照表) mapping Chinese terms to English parameters

Terminology Resource

The terminology resource provides a comprehensive glossary that helps LLMs:

• Map Chinese terms like "清单" (project), "收集箱" (inbox), "任务" (task) to correct tool parameters
• Understand priority levels: 高(high)=5, 中(medium)=3, 低(low)=1, 无(none)=0
• Convert common Chinese user requests to appropriate tool calls

Example mappings:

Chinese Request	English Meaning	Tool to Use
把任务添加到收集箱	Add task to inbox	create_task with projectId: "inbox"
创建新清单	Create new project	create_project
查看今天的任务	View today's tasks	list_tasks with preset: "today"

📁 Project Structure

src/
├── index.ts              # Server main entry
├── oauth.ts              # OAuth2 manager
├── oauth-server.ts       # Local callback server
├── config.ts             # Configuration management
├── token.ts              # Token persistence
├── utils/                # Utility modules
│   └── batch.ts          # Batch execution utilities
├── resources/            # MCP resources
│   ├── index.ts          # Resource registration
│   └── terminology.ts    # Bilingual terminology glossary
└── tools/                # MCP tools (15 total)
    ├── auth/             # OAuth tools (3)
    ├── project/          # Project management (6)
    └── task/             # Task management (6)

🗺️ Roadmap

✅ Completed

• 100% Official API Coverage
• OAuth2 authorization with auto-refresh
• Complete project management (CRUD)
• Complete task management (subtasks, reminders, repeat)
• Read-only mode for AI agents
• Batch operations support (create/update/delete/complete multiple tasks)
• List tasks with filtering (cross-project queries, date/priority filters)
• Inbox task operations support
• Bilingual tool descriptions for Chinese users (中英双语工具描述)
• MCP Resource for terminology glossary (术语对照表资源)

🚀 Next Steps

• Add parameters to limit the ProjectId that the MCP can access

💡 Future Ideas

• Smart task suggestions
• Natural language date/time parsing
• Task templates and automation
• Integration with other productivity tools

🤝 Contribution & Support

If this project helps you, the best way to support it is to give the project a ⭐ on GitHub — it helps others discover the work. Thank you! Your support is much appreciated ❤️

Submit Issues

If you find any issues or have improvement suggestions, welcome to submit an Issue:

1. Visit Issues page
2. Click "New Issue"
3. Describe your problem or suggestion in detail

Join Development

1. Fork the project
2. Create your feature branch (git checkout -b feature/new-feature)
3. Commit your changes (git commit -m 'feat: implement new feature')
4. Push to the branch (git push origin feature/new-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Related Links

• MCP Official Site
• MCP TypeScript SDK
• Dida365 API Documentation
• 中文版本

---