# ClickUp MCP Server

A Model Context Protocol (MCP) server that provides integration with ClickUp's project management platform. This server allows AI assistants to interact with ClickUp workspaces, manage tasks, lists, and projects programmatically.

## Features

### Task Management
- **create_task**: Create new tasks with detailed configuration
- **get_task**: Retrieve task details by ID
- **update_task**: Modify existing tasks
- **delete_task**: Remove tasks
- **list_tasks**: Get tasks from lists with filtering options
- **search_tasks**: Search tasks across workspaces

### Workspace Management
- **get_workspaces**: List accessible workspaces
- **get_workspace_members**: View workspace team members
- **get_spaces**: List spaces within workspaces
- **create_workspace_audit_log**: Create audit log entries (Enterprise only)

### List Management
- **get_lists**: Retrieve lists from spaces
- **create_list**: Create new lists
- **update_list**: Modify existing lists
- **delete_list**: Remove lists

## Installation

1. Clone this repository:
```bash
git clone <repository-url>
cd clickup-mcp
```

2. Install dependencies:
```bash
pip install -r requirements.txt
```

Or install in development mode:
```bash
pip install -e .
```

## Configuration

1. Copy the environment template:
```bash
cp .env.example .env
```

2. Set your ClickUp API token in `.env`:
```env
CLICKUP_API_TOKEN=your_clickup_api_token_here
CLICKUP_WORKSPACE_ID=your_workspace_id_here
```

### Getting Your ClickUp API Token

1. Go to your ClickUp settings
2. Navigate to "Apps" section
3. Generate a new API token
4. Copy the token to your `.env` file

## Usage

### Running the Server

Start the MCP server:
```bash
python __main__.py
```

Or using the module:
```bash
python -m src.server
```

### Integration with Claude Desktop

Add the following to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "clickup": {
      "command": "python",
      "args": ["__main__.py"],
      "cwd": "/path/to/clickup-mcp",
      "env": {
        "CLICKUP_API_TOKEN": "your_token_here"
      }
    }
  }
}
```

## API Reference

### Task Tools

#### create_task
Create a new task in a ClickUp list.

**Parameters:**
- `list_id` (required): ID of the list to create the task in
- `name` (required): Task name/title
- `description` (optional): Task description
- `assignees` (optional): Array of user IDs to assign
- `status` (optional): Task status
- `priority` (optional): Priority level (1=urgent, 2=high, 3=normal, 4=low)
- `due_date` (optional): Due date in Unix timestamp milliseconds
- `tags` (optional): Array of tag names

#### get_task
Retrieve details of a specific task.

**Parameters:**
- `task_id` (required): ID of the task to retrieve

#### update_task
Update an existing task.

**Parameters:**
- `task_id` (required): ID of the task to update
- All other parameters from `create_task` are optional

#### list_tasks
Get tasks from a list with optional filtering.

**Parameters:**
- `list_id` (required): ID of the list
- `archived` (optional): Include archived tasks
- `page` (optional): Page number for pagination
- `order_by` (optional): Field to order by
- `statuses` (optional): Filter by specific statuses
- `assignees` (optional): Filter by assignee user IDs
- `tags` (optional): Filter by tag names
- Various date filters available

### Workspace Tools

#### get_workspaces
Get all workspaces accessible to the user.

#### get_workspace_members
Get members of a specific workspace.

**Parameters:**
- `workspace_id` (required): ID of the workspace

#### get_spaces
Get all spaces in a workspace.

**Parameters:**
- `workspace_id` (required): ID of the workspace

### List Tools

#### create_list
Create a new list in a space.

**Parameters:**
- `space_id` (required): ID of the space
- `name` (required): List name
- `content` (optional): List description
- `priority` (optional): Priority level
- `assignee` (optional): User ID to assign

## Error Handling

The server includes comprehensive error handling for:
- Authentication failures
- Rate limiting
- Resource not found
- Permission errors
- Network issues

All errors are properly formatted and returned as tool responses.

## Security Considerations

- API tokens are loaded from environment variables
- All requests include proper authentication headers
- Rate limiting is handled gracefully
- No sensitive information is logged

## Development

### Project Structure

```
clickup-mcp/
├── __main__.py           # Main entry point
├── src/
│   ├── server.py          # Main MCP server
│   ├── clickup_client.py  # ClickUp API client
│   ├── schemas.py         # Schema definitions
│   ├── tools/             # Tool implementations
│   │   ├── tasks.py       # Task management tools
│   │   ├── workspaces.py  # Workspace tools
│   │   └── lists.py       # List management tools
│   └── utils/             # Utilities
│       ├── auth.py        # Authentication handling
│       └── exceptions.py  # Custom exceptions
├── requirements.txt       # Python dependencies
├── setup.py              # Package configuration
├── .env.example          # Environment template
├── mcp_config.json       # MCP configuration
└── README.md             # This file
```

### Adding New Tools

1. Create a new tool class in the appropriate module
2. Implement the tool schema and handler
3. Register the tool in the main server

### Testing

Test individual API calls:
```bash
python -c "from src.clickup_client import ClickUpClient; client = ClickUpClient(); print(client.get_workspaces())"
```

Test the server:
```bash
python __main__.py
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

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

## Support

For issues and questions:
1. Check the ClickUp API documentation: https://developer.clickup.com/
2. Review the MCP specification: https://modelcontextprotocol.io/
3. Open an issue in this repository

## Changelog

### v1.0.0
- Initial release
- Task management tools
- Workspace management tools
- List management tools
- Audit log support (Enterprise)
- Comprehensive error handling