README.md•6.36 kB
# 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