# ClickUp MCP Server
A robust [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for [ClickUp](https://clickup.com/). This server enables AI assistants (like OpenCode, Claude Desktop, etc.) to interact directly with your ClickUp workspace, allowing for natural language management of tasks, lists, folders, and more.
Unlike official adapters that may rely on limited proxies, this implementation connects directly to the **ClickUp REST API v2**, providing improved reliability and deep integration.
## ✨ Features
- **Full Hierarchy Management**: Create, update, and delete **Spaces**, **Folders**, and **Lists**.
- **Task Operations**: Create tasks, update status/details, fetch comments, and read custom fields.
- **Tagging System**: Manage tags (create/edit/delete) and apply them to tasks.
- **Time Tracking**: Start and stop timers, view time entries.
- **Context Awareness**: Inspect list schemas (statuses, custom fields) and user details.
- **Search**: (Limited) search for tasks within workspaces.
## 🚀 Quick Start
### Prerequisites
- Node.js v18+
- A ClickUp Account
- A ClickUp OAuth App (Client ID & Secret). [Create one here](https://clickup.com/api/developer-portal/).
### Installation
```bash
git clone https://github.com/yourusername/clickup-mcp.git
cd clickup-mcp
npm install
npm run build
```
### Configuration & Authentication
1. **Configure Credentials**:
```bash
node dist/cli.js configure <YOUR_CLIENT_ID> <YOUR_CLIENT_SECRET>
```
2. **Login**:
```bash
node dist/cli.js login
```
This will open your browser to authenticate with ClickUp.
### Integration with OpenCode
Run the registration script to add this server to your OpenCode configuration:
```powershell
powershell -ExecutionPolicy Bypass -File scripts/register.ps1
```
Restart OpenCode, and the "ClickUp" tools will appear.
## 🛠️ Available Tools
The server exposes the following tools to the AI:
### Task Management
- `get_tasks` / `get_task`: Read tasks.
- `create_task` / `update_task`: Modify tasks.
- `get_comments` / `create_comment`: Collaborative features.
### Hierarchy & Structure (CRUD)
- **Workspaces (Teams)**: `get_workspaces`
- **Spaces**: `get_spaces`, `create_space`, `update_space`, `delete_space`
- **Folders**: `get_folders`, `create_folder`, `update_folder`, `delete_folder`
- **Lists**: `get_lists`, `create_list_in_folder`, `create_list_in_space`, `update_list`, `delete_list`
### Schema & Metadata
- `get_list_details`: View list statuses, defaults, and configuration.
- `get_accessible_custom_fields`: View available custom fields for a list.
- `get_current_user`: Identify the authenticated user.
### Tags
- `get_tags`: List available tags.
- `create_tag` / `edit_tag` / `delete_tag`: Manage the tag library.
- `add_tag_to_task` / `remove_tag_from_task`: Apply tags.
### Time Tracking
- `get_time_entries`: View logs.
- `start_timer` / `stop_timer`: Control active sessions.
## 💻 Development
This project is built with **TypeScript** and **Axios**.
- **Build**: `npm run build`
- **Test**: `npm test` (Runs comprehensive unit tests with 100% coverage)
- **Lint**: `npm run lint`
## License
MIT
