# ClickUp MCP Server

A Model Context Protocol (MCP) server that enables Claude Desktop to interact with ClickUp through natural language commands.

## Features

- **User Management**: Get current user profile and verify authentication
- **Task Management**: Complete CRUD operations - get, create, update, delete tasks
- **Task Listing**: List and filter tasks with pagination
- **Natural Language**: Ask Claude to manage your ClickUp workspace in plain English

## Quick Start

1. **Install**: `python -m pip install -e .`
2. **Configure**: Add to Claude Desktop config with your `CLICKUP_API_TOKEN`
3. **Test**: Ask Claude "Use the clickup server to get my user profile"
4. **Create**: "Create a task named 'Test Task' in list LIST_ID"

## Installation

### Prerequisites

- Python 3.10 or higher
- ClickUp API token ([get one here](https://app.clickup.com/settings/apps))

### Local Development

1. Clone the repository:
```bash
git clone https://github.com/deniskrds/clickup-mcp-server.git
cd clickup-mcp-server
```

2. Create a virtual environment:
```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

3. Install the package:
```bash
python -m pip install -e .
```

4. Create environment file:
```bash
cp .env.example .env
# Edit .env and add your CLICKUP_API_TOKEN
```

## Claude Desktop Setup

1. Open Claude Desktop configuration:
   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

2. Add the MCP server configuration:
```json
{
  "mcpServers": {
    "clickup": {
      "command": "clickup-mcp",
      "env": {
        "CLICKUP_API_TOKEN": "your_token_here"
      }
    }
  }
}
```

3. Restart Claude Desktop

## Usage

Once configured, you can ask Claude to manage your ClickUp workspace:

### User & Authentication
- "Use the clickup server to get my user profile"
- "Verify my ClickUp authentication"

### Task Management
- "Use the clickup server to create a task named 'Review PR' in list LIST_ID"
- "Update task TASK_ID: set status to 'In Progress'"
- "List tasks in list LIST_ID with status 'Open'"
- "Get task TASK_ID details"
- "Delete task TASK_ID"

### Example Workflow
1. **Create task**: "Use the clickup server to create a task named 'Review PR #456' in list LIST_ID"
2. **Get task details**: "Get task TASK_ID to see the created task"
3. **Update task**: "Update task TASK_ID: set status to 'In Progress' and assign to user 123"
4. **Complete task**: "Update task TASK_ID: set status to 'Complete'"

## Available Tools

| Tool | Description | Parameters |
|------|-------------|------------|
| `get_user` | Get current user profile | None |
| `get_task` | Get specific task details | `task_id` |
| `create_task` | Create new task | `list_id`, `name`, `description`, `assignees`, `tags`, `status`, `priority`, `due_date` |
| `update_task` | Update existing task | `task_id`, `name`, `description`, `assignees`, `tags`, `status`, `priority`, `due_date` |
| `delete_task` | Delete a task | `task_id` |
| `list_tasks` | List tasks in a list | `list_id`, `page`, `limit`, `status`, `assignees` |

## Configuration

The server uses environment variables for configuration:

```bash
# Required
CLICKUP_API_TOKEN=your_clickup_token

# Optional (defaults shown)
CLICKUP_APP_ENV=development
CLICKUP_BASE_URL=https://api.clickup.com/api/v2
CLICKUP_REQUEST_TIMEOUT_SECONDS=15
CLICKUP_MAX_RETRIES=2
CLICKUP_RETRY_BACKOFF_SECONDS=0.5
```

## Development

### Project Structure
```
clickup_mcp/
├── clickup/          # ClickUp API client
├── tools/            # Task management tools
├── models.py         # Pydantic models
├── config.py         # Configuration management
└── mcp_server.py     # MCP server entry point

tests/
└── test_mcp_server.py # Unit tests
```

### Adding New Tools
1. Implement helper functions in `clickup_mcp/tools/`
2. Register tools in `clickup_mcp/mcp_server.py`
3. Add clear docstrings and parameter types

## Troubleshooting

**"Server disconnected" error:**
- Ensure `clickup-mcp` command is in your PATH
- Check that `CLICKUP_API_TOKEN` is set correctly
- Verify Python version is 3.10+

**"Module not found" errors:**
- Reinstall the package: `python -m pip install -e .`
- Activate your virtual environment

**Claude can't find the server:**
- Use absolute path in Claude config: `/full/path/to/venv/bin/clickup-mcp`
- Restart Claude Desktop after config changes

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

## Contributing

Contributions are welcome! Please open an issue or submit a pull request.

## Contact

For questions or support, please open an issue on GitHub.