# TickTick MCP v2
A Model Context Protocol (MCP) server for TickTick that enables interacting with your TickTick task management system directly through Claude and other MCP clients.
## Features
- 📋 View all your TickTick projects and tasks
- ✏️ Create new projects and tasks through natural language
- 🔄 Update existing task details (title, content, dates, priority)
- ✅ Mark tasks as complete
- 🗑️ Delete tasks and projects
- 🔐 Username/password authentication with local credential storage
## Quick Start
### 1. Install Dependencies
```bash
git clone <repository-url>
cd ticktick-mcp-v2
# Initialize and update Git submodules
git submodule update --init --recursive
uv pip install -r requirements.txt
```
### 2. Authenticate
```bash
uv run ticktick-mcp auth
```
Enter your TickTick username and password when prompted. Credentials will be saved locally.
### 3. Test Configuration
```bash
uv run ticktick-mcp test
```
### 4. Run Server
```bash
uv run ticktick-mcp run
```
## Integration with Claude Desktop
1. Edit your Claude Desktop configuration file:
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
2. Add the MCP server configuration:
**Option 1: Auto-authentication (Recommended)**
```json
{
"mcpServers": {
"ticktick-mcp-v2": {
"command": "uv",
"args": [
"run",
"--directory",
"/absolute/path/to/your/ticktick-mcp-v2",
"ticktick-mcp",
"run"
],
"env": {
"TICKTICK_USERNAME": "your_username_here",
"TICKTICK_PASSWORD": "your_password_here"
}
}
}
}
```
**Option 2: Manual authentication**
```json
{
"mcpServers": {
"ticktick-mcp-v2": {
"command": "uv",
"args": [
"run",
"--directory",
"/absolute/path/to/your/ticktick-mcp-v2",
"ticktick-mcp",
"run"
]
}
}
}
```
3. Restart Claude Desktop
## Available MCP Tools
| Tool | Description | Parameters |
|------|-------------|------------|
| **Authentication** |
| `auth_status` | Check authentication status | None |
| **Project Management** |
| `get_projects` | List all projects | None |
| `get_project` | Get project details | `project_id` |
| `create_project` | Create new project | `name`, `color` (optional), `view_mode` (optional) |
| `delete_project` | Delete project | `project_id` |
| `get_project_tasks` | Get tasks in project | `project_id`, `include_completed` (optional) |
| **Task Management** |
| `get_tasks` | List all tasks | `include_completed` (optional) |
| `create_task` | Create new task | `title`, `project_id` (optional), `content` (optional), `start_date` (optional), `due_date` (optional), `priority` (optional) |
| `update_task` | Update task | `task_id`, `project_id` (optional), `title` (optional), `content` (optional), `start_date` (optional), `due_date` (optional), `priority` (optional) |
| `delete_task` | Delete task | `project_id`, `task_id` |
| `complete_task` | Mark task complete | `task_id` |
| **Advanced Features** |
| `search_tasks` | Search tasks | `query` |
| `get_tasks_by_priority` | Get tasks by priority | `priority` (0=None, 1=Low, 3=Medium, 5=High) |
| `get_tasks_due_today` | Get tasks due today | None |
| `get_overdue_tasks` | Get overdue tasks | None |
## Example Prompts
- "Show me all my TickTick projects"
- "Create a task called 'Finish documentation' with high priority"
- "What tasks do I have due today?"
- "Mark the task 'Buy groceries' as complete"
## CLI Commands
- `auth` - Authenticate with TickTick
- `run` - Run the MCP server
- `test` - Test configuration
- `logout` - Clear saved credentials
## Authentication
This server supports multiple authentication methods:
1. **CLI Authentication** (Primary): `uv run ticktick-mcp auth`
2. **Environment Variables**: Set `TICKTICK_USERNAME` and `TICKTICK_PASSWORD`
3. **MCP Config**: Add credentials in Claude Desktop config
4. **Local Storage**: Credentials saved to `~/.ticktick-mcp/credentials.json`
### Running Tests
```bash
python -m pytest tests/
```
## Acknowledgments
This project would not be possible without the excellent work of the following open source projects:
### 🎯 [ticktick-py](https://github.com/lazeroffmichael/ticktick-py)
**Original Author**: [Michael Lazeroff](https://github.com/lazeroffmichael)
**Fork Maintainer**: [yidianyiko](https://github.com/yidianyiko)
The core TickTick Python SDK that powers this MCP server. This unofficial API library provides comprehensive access to TickTick's functionality, enabling seamless integration with the TickTick task management platform.
### 🤝 Contributing
If you find this project useful, please consider:
- ⭐ Starring the maintained [fork repository](https://github.com/yidianyiko/ticktick-py)
- 🐛 Reporting issues or suggesting improvements
- 📖 Contributing to documentation
## License
MIT License - see LICENSE file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "ticktick-mcp-v2",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ticktick, mcp, model-context-protocol, task-management",
"author": null,
"author_email": "TickTick MCP Team <dev@example.com>",
"download_url": "https://files.pythonhosted.org/packages/ef/bc/9956a0c9c214fcca6da495ffdf643a43bc0347a2212c7ac810fd233523e0/ticktick_mcp_v2-1.0.1.tar.gz",
"platform": null,
"description": "# TickTick MCP v2\n\nA Model Context Protocol (MCP) server for TickTick that enables interacting with your TickTick task management system directly through Claude and other MCP clients.\n\n## Features\n\n- \ud83d\udccb View all your TickTick projects and tasks\n- \u270f\ufe0f Create new projects and tasks through natural language\n- \ud83d\udd04 Update existing task details (title, content, dates, priority)\n- \u2705 Mark tasks as complete\n- \ud83d\uddd1\ufe0f Delete tasks and projects\n- \ud83d\udd10 Username/password authentication with local credential storage\n\n## Quick Start\n\n### 1. Install Dependencies\n```bash\ngit clone <repository-url>\ncd ticktick-mcp-v2\n# Initialize and update Git submodules\ngit submodule update --init --recursive\nuv pip install -r requirements.txt\n```\n\n### 2. Authenticate\n```bash\nuv run ticktick-mcp auth\n```\nEnter your TickTick username and password when prompted. Credentials will be saved locally.\n\n### 3. Test Configuration\n```bash\nuv run ticktick-mcp test\n```\n\n### 4. Run Server\n```bash\nuv run ticktick-mcp run\n```\n\n## Integration with Claude Desktop\n\n1. Edit your Claude Desktop configuration file:\n **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n2. Add the MCP server configuration:\n\n **Option 1: Auto-authentication (Recommended)**\n ```json\n {\n \"mcpServers\": {\n \"ticktick-mcp-v2\": {\n \"command\": \"uv\",\n \"args\": [\n \"run\",\n \"--directory\", \n \"/absolute/path/to/your/ticktick-mcp-v2\",\n \"ticktick-mcp\",\n \"run\"\n ],\n \"env\": {\n \"TICKTICK_USERNAME\": \"your_username_here\",\n \"TICKTICK_PASSWORD\": \"your_password_here\"\n }\n }\n }\n }\n ```\n\n **Option 2: Manual authentication**\n ```json\n {\n \"mcpServers\": {\n \"ticktick-mcp-v2\": {\n \"command\": \"uv\",\n \"args\": [\n \"run\",\n \"--directory\", \n \"/absolute/path/to/your/ticktick-mcp-v2\",\n \"ticktick-mcp\",\n \"run\"\n ]\n }\n }\n }\n ```\n\n3. Restart Claude Desktop\n\n## Available MCP Tools\n\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| **Authentication** |\n| `auth_status` | Check authentication status | None |\n| **Project Management** |\n| `get_projects` | List all projects | None |\n| `get_project` | Get project details | `project_id` |\n| `create_project` | Create new project | `name`, `color` (optional), `view_mode` (optional) |\n| `delete_project` | Delete project | `project_id` |\n| `get_project_tasks` | Get tasks in project | `project_id`, `include_completed` (optional) |\n| **Task Management** |\n| `get_tasks` | List all tasks | `include_completed` (optional) |\n| `create_task` | Create new task | `title`, `project_id` (optional), `content` (optional), `start_date` (optional), `due_date` (optional), `priority` (optional) |\n| `update_task` | Update task | `task_id`, `project_id` (optional), `title` (optional), `content` (optional), `start_date` (optional), `due_date` (optional), `priority` (optional) |\n| `delete_task` | Delete task | `project_id`, `task_id` |\n| `complete_task` | Mark task complete | `task_id` |\n| **Advanced Features** |\n| `search_tasks` | Search tasks | `query` |\n| `get_tasks_by_priority` | Get tasks by priority | `priority` (0=None, 1=Low, 3=Medium, 5=High) |\n| `get_tasks_due_today` | Get tasks due today | None |\n| `get_overdue_tasks` | Get overdue tasks | None |\n\n## Example Prompts\n\n- \"Show me all my TickTick projects\"\n- \"Create a task called 'Finish documentation' with high priority\"\n- \"What tasks do I have due today?\"\n- \"Mark the task 'Buy groceries' as complete\"\n\n## CLI Commands\n\n- `auth` - Authenticate with TickTick\n- `run` - Run the MCP server\n- `test` - Test configuration\n- `logout` - Clear saved credentials\n\n## Authentication\n\nThis server supports multiple authentication methods:\n\n1. **CLI Authentication** (Primary): `uv run ticktick-mcp auth`\n2. **Environment Variables**: Set `TICKTICK_USERNAME` and `TICKTICK_PASSWORD`\n3. **MCP Config**: Add credentials in Claude Desktop config\n4. **Local Storage**: Credentials saved to `~/.ticktick-mcp/credentials.json`\n\n### Running Tests\n```bash\npython -m pytest tests/\n```\n## Acknowledgments\n\nThis project would not be possible without the excellent work of the following open source projects:\n\n### \ud83c\udfaf [ticktick-py](https://github.com/lazeroffmichael/ticktick-py)\n**Original Author**: [Michael Lazeroff](https://github.com/lazeroffmichael) \n**Fork Maintainer**: [yidianyiko](https://github.com/yidianyiko)\n\nThe core TickTick Python SDK that powers this MCP server. This unofficial API library provides comprehensive access to TickTick's functionality, enabling seamless integration with the TickTick task management platform.\n\n\n### \ud83e\udd1d Contributing\n\nIf you find this project useful, please consider:\n- \u2b50 Starring the maintained [fork repository](https://github.com/yidianyiko/ticktick-py)\n- \ud83d\udc1b Reporting issues or suggesting improvements\n- \ud83d\udcd6 Contributing to documentation\n\n## License\n\nMIT License - see LICENSE file for details. \n",
"bugtrack_url": null,
"license": "MIT",
"summary": "TickTick MCP Server - Enhanced Version with Chinese Support",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/example/ticktick-mcp-v2",
"Issues": "https://github.com/example/ticktick-mcp-v2/issues",
"Repository": "https://github.com/example/ticktick-mcp-v2"
},
"split_keywords": [
"ticktick",
" mcp",
" model-context-protocol",
" task-management"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c6f6e521dce8a0bb72bc11146f8e67f3c6def1052dfac3dc46ddd40eba246edc",
"md5": "007a75de4e21617d8f4ff47a3eff5e15",
"sha256": "655eefe818d2e256bfca1b16567f0e8c25e412d1a82b0514a569279e73a2827d"
},
"downloads": -1,
"filename": "ticktick_mcp_v2-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "007a75de4e21617d8f4ff47a3eff5e15",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 87955,
"upload_time": "2025-08-02T09:46:43",
"upload_time_iso_8601": "2025-08-02T09:46:43.715553Z",
"url": "https://files.pythonhosted.org/packages/c6/f6/e521dce8a0bb72bc11146f8e67f3c6def1052dfac3dc46ddd40eba246edc/ticktick_mcp_v2-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "efbc9956a0c9c214fcca6da495ffdf643a43bc0347a2212c7ac810fd233523e0",
"md5": "2d68073e24f311d27e6481de7fe03306",
"sha256": "d1f41bbd49f03eeb9007ac80a8f4f1e4cd28ecc73009d0e16402daed5158ee2f"
},
"downloads": -1,
"filename": "ticktick_mcp_v2-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "2d68073e24f311d27e6481de7fe03306",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 76457,
"upload_time": "2025-08-02T09:46:45",
"upload_time_iso_8601": "2025-08-02T09:46:45.938066Z",
"url": "https://files.pythonhosted.org/packages/ef/bc/9956a0c9c214fcca6da495ffdf643a43bc0347a2212c7ac810fd233523e0/ticktick_mcp_v2-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-02 09:46:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "example",
"github_project": "ticktick-mcp-v2",
"github_not_found": true,
"lcname": "ticktick-mcp-v2"
}
JSON
