@s.pawel940/clickup-mcp-server v0.7.4

ClickUp MCP Server (Read-Only Version)

A read-only Model Context Protocol (MCP) server for integrating ClickUp tasks with AI applications. This read-only version was created by ToSn0w. This server allows AI agents to retrieve information from ClickUp tasks, spaces, lists, and folders through a standardized protocol.

Find the package on npm: https://www.npmjs.com/package/@s.pawel940/clickup-mcp-server

🚀 Status Update: v0.7.2 now available with complete Time Tracking support and Document Management features. Key features include:

• Task information retrieval
• Workspace organization viewing
• Time tracking data access
• Member information access
• Document content viewing
• Built-in rate limiting and error handling

Setup

1. Get your credentials:
   • ClickUp API key from ClickUp Settings
   • Team ID from your ClickUp workspace URL
2. Choose your installation method:
   • Smithery Installation (hosted with webhooks)
   • NPX Installation (local with dependencies)
   • Docker Installation (containerized)
3. Configure environment variables and start using natural language to view your workspace!

Smithery Installation (Quick Start)

The server is hosted on Smithery. There, you can preview the available tools or copy the commands to run on your specific client app.

NPX Installation

Add this entry to your client's MCP settings JSON file:

{
  "mcpServers": {
    "ClickUp": {
      "command": "npx",
      "args": [
        "-y",
        "@s.pawel940/clickup-mcp-server@latest"
      ],
      "env": {
        "CLICKUP_API_KEY": "your-api-key",
        "CLICKUP_TEAM_ID": "your-team-id",
        "DOCUMENT_SUPPORT": "true"
      }
    }
  }
}

Or use this npx command:

npx -y @s.pawel940/clickup-mcp-server@latest --env CLICKUP_API_KEY=your-api-key --env CLICKUP_TEAM_ID=your-team-id

Obs: if you don't pass "DOCUMENT_SUPPORT": "true", the default is false and document support will not be active.

Additionally, you can use the DISABLED_TOOLS environment variable or --env DISABLED_TOOLS argument to disable specific tools. Provide a comma-separated list of tool names to disable (e.g., create_task,delete_task).

Please disable tools you don't need if you are having issues with the number of tools or any context limitations

Running with SSE Support

Server can be run in SSE (Server-Sent Events) mode by setting the following environment variables:

{
  "mcpServers": {
    "ClickUp": {
      "command": "npx",
      "args": [
        "-y",
        "@s.pawel940/clickup-mcp-server@latest"
      ],
      "env": {
        "CLICKUP_API_KEY": "your-api-key",
        "CLICKUP_TEAM_ID": "your-team-id",
        "ENABLE_SSE": "true",
        "PORT": "8000"  // Optional, defaults to 3231
      }
    }
  }
}

Or via command line:

npx -y @s.pawel940/clickup-mcp-server@latest --env CLICKUP_API_KEY=your-api-key --env CLICKUP_TEAM_ID=your-team-id --env ENABLE_SSE=true --env PORT=8000

Docker-compose example

version: '3.8'

services:
  clickup-mcp-server:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - '3231:8000'
    environment:
      - CLICKUP_API_KEY=${CLICKUP_API_KEY}
      - CLICKUP_TEAM_ID=${CLICKUP_TEAM_ID}
      - ENABLE_SSE=true
      - LOG_LEVEL=info
      - DOCUMENT_SUPPORT=true
    volumes:
      - ./src:/app/src
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 5s

For n8n integration, see the example in examples/n8n/docker-compose.yml.

Available Tools (Read-Only)

Prompts

Not yet implemented and not supported by all client apps. Request a feature for a Prompt implementation that would be most beneficial for your workflow (without it being too specific). Examples:

Error Handling

The server provides clear error messages for:

• Missing required parameters
• Invalid IDs or names
• Items not found
• Permission issues
• API errors
• Rate limiting

The LOG_LEVEL environment variable can be specified to control the verbosity of server logs. Valid values are trace, debug, info, warn, and error (default). This can be also be specified on the command line as, e.g. --env LOG_LEVEL=info.

Acknowledgements

Special thanks to ClickUp for their excellent API and services that make this integration possible.

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

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

Disclaimer

This software makes use of third-party APIs and may reference trademarks or brands owned by third parties. The use of such APIs or references does not imply any affiliation with or endorsement by the respective companies. All trademarks and brand names are the property of their respective owners. This project is an independent work and is not officially associated with or sponsored by any third-party company mentioned.

Environment Variables

The server supports the following environment variables:

• CLICKUP_API_KEY (required): Your ClickUp API key
• CLICKUP_TEAM_ID (required): Your ClickUp team/workspace ID
• DOCUMENT_SUPPORT (optional): Enable document management features (default: false)
• ENABLE_SSE (optional): Enable Server-Sent Events mode (default: false)
• PORT (optional): Server port in SSE mode (default: 3231)
• LOG_LEVEL (optional): Logging level (TRACE, DEBUG, INFO, WARN, ERROR)
• DISABLED_TOOLS (optional): Comma-separated list of tools to disable

Docker Support

The server can be run as a Docker container. Here's a basic example using docker-compose:

version: '3.8'

services:
  clickup-mcp-server:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - '3231:8000'
    environment:
      - CLICKUP_API_KEY=${CLICKUP_API_KEY}
      - CLICKUP_TEAM_ID=${CLICKUP_TEAM_ID}
      - ENABLE_SSE=true
      - LOG_LEVEL=info
      - DOCUMENT_SUPPORT=true
    volumes:
      - ./src:/app/src
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 5s

For n8n integration, see the example in examples/n8n/docker-compose.yml.

Quick Installation Guide for n8n Users

1. Install the n8n-nodes-mcp community node:

npm install n8n-nodes-mcp

2. Install and run the read-only ClickUp MCP Server using NPX: Follow the instructions in the NPX Installation section to install and run the @s.pawel940/clickup-mcp-server package. Ensure you set your CLICKUP_API_KEY and CLICKUP_TEAM_ID environment variables.

3. Configure the MCP Server in n8n:

   • In your n8n workflow, add an MCP Server node.
   • Configure the node to connect to the running MCP Server. If running locally via NPX, the default URL is http://localhost:3231. If you configured a different port or are running it elsewhere, use that address.

4. Available Tools for n8n Integration:

   • Document Management:
     • get_document: Retrieve document details
     • list_documents: List all documents
     • list_document_pages: List pages in a document
     • get_document_pages: Get specific document pages
   • List Management:
     • get_list: Get list details
     • get_folder: Get folder details
     • get_space_tags: Get space tags