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
- Clone this repository:
git clone <repository-url>
cd clickup-mcp
- Install dependencies:
pip install -r requirements.txt
Or install in development mode:
pip install -e .
Configuration
- Copy the environment template:
cp .env.example .env
- Set your ClickUp API token in
.env:
CLICKUP_API_TOKEN=your_clickup_api_token_here
CLICKUP_WORKSPACE_ID=your_workspace_id_here
Getting Your ClickUp API Token
- Go to your ClickUp settings
- Navigate to "Apps" section
- Generate a new API token
- Copy the token to your
.envfile
Usage
Running the Server
Start the MCP server:
python __main__.py
Or using the module:
python -m src.server
Integration with Claude Desktop
Add the following to your Claude Desktop configuration:
{
"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 inname(required): Task name/titledescription(optional): Task descriptionassignees(optional): Array of user IDs to assignstatus(optional): Task statuspriority(optional): Priority level (1=urgent, 2=high, 3=normal, 4=low)due_date(optional): Due date in Unix timestamp millisecondstags(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_taskare optional
list_tasks
Get tasks from a list with optional filtering.
Parameters:
list_id(required): ID of the listarchived(optional): Include archived taskspage(optional): Page number for paginationorder_by(optional): Field to order bystatuses(optional): Filter by specific statusesassignees(optional): Filter by assignee user IDstags(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 spacename(required): List namecontent(optional): List descriptionpriority(optional): Priority levelassignee(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
- Create a new tool class in the appropriate module
- Implement the tool schema and handler
- Register the tool in the main server
Testing
Test individual API calls:
python -c "from src.clickup_client import ClickUpClient; client = ClickUpClient(); print(client.get_workspaces())"
Test the server:
python __main__.py
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
License
This project is licensed under the MIT License - see the LICENSE file for details.
Support
For issues and questions:
- Check the ClickUp API documentation: https://developer.clickup.com/
- Review the MCP specification: https://modelcontextprotocol.io/
- 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