Development Requirements

Before you begin contributing to ClickUp MCP Server, ensure your development environment meets these requirements.

Software Prerequisites

Required Software

• Python: Python 3.13 or higher
• Git: Latest stable version
• pip, poetry or uv: Latest version
• virtualenv or pyenv: For creating isolated Python environments

Recommended Development Tools

• Visual Studio Code, PyCharm, or other IDE with Python support
• pre-commit: For running pre-commit hooks
• Docker: For containerized testing and deployment

Python Dependencies

The project has several dependencies that will be installed automatically when you set up the development environment:

• FastAPI: Web framework for API endpoints
• Pydantic: Data validation and settings management
• httpx: HTTP client for async requests
• pytest: Testing framework
• python-dotenv: Environment variable management
• uvicorn: ASGI server for running the application

Development Environment Setup

1. Clone the repository:

   git clone https://github.com/Chisanan232/clickup-mcp-server.git
   cd clickup-mcp-server

2. Create a virtual environment:

   virtualenv

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

   conda

   conda create -n clickup-mcp python=3.13
   conda activate clickup-mcp

   poetry

   poetry shell

   uv

   uv venv
   source .venv/bin/activate

3. Install development dependencies:

   pip

   pip install -e ".[dev]"

   poetry

   poetry install --with=dev

   uv

   uv pip install .

4. Set up pre-commit hooks:

   pip

   pre-commit install

   poetry

   poetry run pre-commit install

   uv

   uv run pre-commit install

5. Create a .env file for local development:

   cp .env.example .env
   # Edit .env with your ClickUp API token

Environment variables for development and tests

note

The following variables are primarily intended for project maintainers and contributors. They are used in local development and automated tests and are not required for typical end-user setups.

Dev/Test-only variables

Variable	Purpose	Example
E2E_TEST_API_TOKEN	Fallback token used by examples/tests when CLICKUP_API_TOKEN is not set.	sk_clickup_test_xxx
CLICKUP_WEBHOOK_HANDLER_MODULES	Comma-separated module paths to auto-import at startup (web server and webhook consumer) for local handlers.	my_app.webhooks.handlers,more.pkg.handlers
QUEUE_BACKEND	Message queue backend selection for webhook producer/consumer. Use local for development.	local

Minimal dev/test .env example:

# Use test token locally when not exporting CLICKUP_API_TOKEN
E2E_TEST_API_TOKEN=sk_clickup_test_XXXXXXXXXXXXXXXX

# Auto-import local webhook handlers
CLICKUP_WEBHOOK_HANDLER_MODULES=my_app.webhooks.handlers

# Use local message queue backend
QUEUE_BACKEND=local

E2E ClickUp IDs (optional)

These IDs support end-to-end tests that create/read/update resources in a real ClickUp workspace.

• CLICKUP_TEST_TEAM_ID — Team/Workspace ID for creating resources during tests
• CLICKUP_TEST_SPACE_ID — Space ID used by some folder/list tests
• CLICKUP_TEST_FOLDER_ID — Folder ID when not creating dynamically
• CLICKUP_TEST_LIST_ID — Primary list for task tests
• CLICKUP_TEST_LIST_ID_2 — Secondary list for multi-list scenarios
• CLICKUP_TEST_CUSTOM_FIELD_ID — Custom field ID used in custom field tests

Next Steps

Once your development environment is set up, refer to the Development Workflow documentation for the next steps.