yihaoWang/clickup-mcp-server

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:

git clone <repository-url>
cd clickup-mcp

2. Install dependencies:

pip install -r requirements.txt

Or install in development mode:

pip install -e .

Configuration

1. Copy the environment template:

cp .env.example .env

2. 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

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:

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 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:

python -c "from src.clickup_client import ClickUpClient; client = ClickUpClient(); print(client.get_workspaces())"

Test the server:

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