ClickUp MCP Server Wrapper

This artifact serves as an implementation of the Model Context Protocol (MCP) server specification, specifically engineered for interacting with ClickUp workspaces via AI entities.

It operates utilizing the Stdio transport mechanism, adhering strictly to the MCP architectural mandate when initiated by a compatible MCP client.

Initialization Guide

Operation necessitates your ClickUp Personal API Token for secure endpoint authorization.

1. Token Acquisition: Navigate to ClickUp preferences ("My Settings" -> "Apps") to provision a valid Personal API Token.
2. Client Configuration: When setting up the host MCP client (e.g., Claude for Desktop), ensure this token is injected via the designated environment variable.

Exemplary client setup JSON structure:

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": ["@nazruden/clickup-server"],
      "env": {
        "CLICKUP_PERSONAL_TOKEN": "your_personal_api_token_here"
      }
    }
  }
}

1. Client Relaunch: Following configuration, restart the calling MCP application.

The component is autonomously fetched and commenced by the client environment upon invocation.

Installation via Smithery Utility

Automated deployment for Claude Desktop consumers via the Smithery orchestration utility:

npx -y @smithery/cli install @Nazruden/clickup-mcp-server --client claude

Operational Environment Variables

Mandated Input

• CLICKUP_PERSONAL_TOKEN: The required authentication credential for all ClickUp API interactions.

Optional Settings

• LOG_LEVEL: Controls verbosity; options include error, warn, info, debug. Default is info.
• ENCRYPTION_KEY: A mandatory 32-byte key, expected in hexadecimal format, intended for configuration persistence. Note: Despite provisioning logic within src/config/app.config.ts and security routines in src/security.ts, this feature is presently inactive regarding the token handling in ClickUpService.
• PORT: Designates a listening port. This is ignored in the default Stdio execution model but is configurable within src/config/app.config.ts (defaulting to 3000) if HTTP transport is ever implemented.

Exposed Toolset

The following functionalities are exposed via the MCP interface:

Task Manipulation

• clickup_create_task: Provision a new task within a specified ClickUp list.
• Necessitates: list_id, name.
• Optional Parameters: description, status, priority, assignees, due_date, time_estimate, tags.
• clickup_update_task: Modify attributes of an extant task.
• Necessitates: task_id.
• Optional Parameters: Any mutable field defined in the ClickUpTask schema.

Team & List Retrieval

• clickup_get_teams: Fetch a registry of all Workspaces accessible to the authenticated user (labeled as Teams in the v2 API).
• clickup_get_lists: Retrieve all associated lists beneath a specified Folder entity.
• Necessitates: folder_id.

Board Operations

• clickup_create_board: Instantiate a new Board within a designated Space.
• Necessitates: space_id, name.

Space Management (Projects/Containers)

• clickup_get_spaces: Fetch all Spaces affiliated with a given Workspace (Team).
• Necessitates: team_id (Workspace ID).
• Optional: archived (boolean, defaults to false).
• clickup_create_space: Initiate a new Space inside a Workspace context.
• Necessitates: team_id (Workspace ID), name.
• Optional: Configuration flags like multiple_assignees or detailed features configuration object.
• clickup_get_space: Fetch granular metadata for a single Space identifier.
• Necessitates: space_id.
• clickup_update_space: Apply modifications to an existing Space definition.
• Necessitates: space_id.
• Optional: Attributes such as name, color, private state, administrative permissions, archiving status, and feature toggles.
• clickup_delete_space: Permanently eliminate a Space entity.
• Necessitates: space_id.

Folder Management

• clickup_get_folders: Retrieve all Folders contained within a specific Space boundary.
• Necessitates: space_id.
• Optional: archived flag (defaults to false).
• clickup_create_folder: Establish a new Folder entity inside a Space.
• Necessitates: space_id, name.
• clickup_get_folder: Fetch detailed records for an individual Folder.
• Necessitates: folder_id.
• clickup_update_folder: Modify the properties of an established Folder.
• Necessitates: folder_id, name.
• clickup_delete_folder: Decommission a Folder.
• Necessitates: folder_id.

Custom Data Field Control

• clickup_get_custom_fields: List all Custom Fields applicable to a given List.
• Necessitates: list_id.
• clickup_set_task_custom_field_value: Assign or overwrite a Custom Field's value on a designated task.
• Necessitates: task_id, field_id, value.
• Optional: value_options (e.g., date field settings).
• clickup_remove_task_custom_field_value: Clear the data entry associated with a Custom Field on a task.
• Necessitates: task_id, field_id.

Documentation (Doc) Interfacing

Caveat: ClickUp's documentation API (often relying on V2 with V3 endpoint migration) presents structural limitations. Content is primarily Markdown-based. Complex formatting or embedded assets may not render perfectly. Direct document annihilation via API is presently unsupported by the V3 /docs route; lifecycle management should target archiving or page content manipulation.

• clickup_search_docs: Execute a textual search across documents within a Workspace (Team context).
• Necessitates: workspace_id.
• Optional: query string, include_archived boolean.
• clickup_create_doc: Generate a new documentation artifact.
• Necessitates: workspace_id, name.
• Optional: parent structure (id, type), visibility setting (private, workspace, public), and page creation flag.
• clickup_get_doc_pages: Retrieve the hierarchical list of contained pages for a specific Doc.
• Necessitates: doc_id.
• clickup_create_doc_page: Establish a fresh page within an existing document structure.
• Necessitates: workspace_id, doc_id, name (the page heading).
• Optional: Initial content (Markdown), ordering index (orderindex), parent page ID, subtitle, and content rendition format.
• clickup_get_doc_page_content: Fetch the raw Markdown payload for a specific document page.
• Necessitates: workspace_id, doc_id, page_id.
• Optional: content_format specifier.
• clickup_edit_doc_page_content: Mutate the title and/or content body of a document page.
• Necessitates: workspace_id, doc_id, page_id, primary content (Markdown).
• Optional: New title, sub_title, content modification strategy (content_edit_mode: "replace", "append", "prepend"), and format specification.

View Configuration Management

• clickup_get_views: Fetch all defined Views associated with a hierarchical parent (Team, Space, Folder, or List).
• Necessitates: parent_id (The ID of the hosting resource), parent_type (designator: "team", "space", "folder", or "list").
• clickup_create_view: Instantiate a new View within any supported parent entity.
• Necessitates: parent_id, parent_type, name (View label), type (e.g., "list", "board", "calendar", "gantt").
• Optional: Configuration objects for layout parameters: grouping, divide, sorting, filters, columns, team_sidebar, and settings.
• clickup_get_view_details: Retrieve comprehensive configuration data for a single View ID.
• Necessitates: view_id.
• clickup_update_view: Modify parameters of an existing View.
• Necessitates: view_id.
• Optional: Renaming, layout adjustments (grouping, divide, sorting, filters, columns), sidebar visibility, and settings payloads.
• clickup_delete_view: Erase a View from the configuration.
• Necessitates: view_id.
• clickup_get_view_tasks: Extract the tasks cataloged within a specific View's scope.
• Necessitates: view_id.
• Optional: page index (zero-based pagination control).

Development Workflow

1. Obtain Source Code: bash git clone <repository_url> cd clickup-mcp-server
2. Dependency Installation: bash npm install
3. Local Environment Setup: Create a root .env file supplying the secret token: env CLICKUP_PERSONAL_TOKEN=your_actual_personal_api_token_here LOG_LEVEL=debug

4. Execute in Development Mode (Stdio): The server monitors standard input for incoming MCP directives.

   bash npm run dev

   This command leverages ts-node-dev to run the primary entry point, src/index.ts.

5. Production Build Compilation:

   bash npm run build

   This action compiles TypeScript sources into the dist/ directory.

6. Running Unit Validation: bash npm test This executes Jest suites residing in src/__tests__. Verify that src/__tests__/setup.ts accounts for necessary environment variables, potentially via a .env.test file.

Verification Using MCP Inspector

Local functional testing with the MCP Inspector:

1. Ensure the CLICKUP_PERSONAL_TOKEN is available, either through direct shell export, configuration within the Inspector UI if supported, or via the local .env file (as src/index.ts utilizes dotenv).
2. Initiate the Inspector connected to this server instance: bash npx @modelcontextprotocol/inspector node --loader ts-node/esm src/index.ts The Inspector's graphical interface should become active, permitting immediate remote tool invocation against this server.

Security Posture

• Authentication relies exclusively on the externally provided ClickUp Personal API Token. Strict confidentiality of this credential is paramount. It must be handled with the same care as a primary password.
• The server requires the token to be securely furnished via an environment variable context provided by the client application or development host.
• While configuration infrastructure supports an ENCRYPTION_KEY and associated routines exist in src/security.ts, these cryptographic safeguards are not currently engaged for protecting the Personal API Token utilized by ClickUpService.
• Default logging (LOG_LEVEL=info) avoids disclosure of sensitive parameters. Debug logging may expose more data.
• ClickUp API request throttling behavior is managed by logging available request quotas (see ClickUpService). The server does not implement custom queuing or exponential backoff mechanisms beyond standard HTTP client defaults.

Diagnostics and Remediation

Frequently Encountered Faults

1. API Authorization Failures (HTTP 401 Responses)

   • Validate the environment variable injection path for CLICKUP_PERSONAL_TOKEN—confirming accessibility by the server runtime.
   • Confirm the token's active status within your ClickUp account interface.
   • Scrutinize server output, specifically messages originating from ClickUpService regarding authorization status.

2. ClickUp Rate Limiting Exceeded

   • The server explicitly reports rate limit headers received from the ClickUp API endpoints.
   • Persistent throttling indicates excessive query volume. The server's current logic does not feature inherent request queuing or complex retry strategies.

3. Startup Failures / Inspector Connectivity Loss

   • Confirm token presence.
   • If using npm run dev, inspect the terminal for TypeScript compilation errors or ts-node-dev exceptions.
   • If using the Inspector invocation (node --loader...), ensure project dependencies, particularly ts-node, are correctly installed.
   • Look for exceptions reported by src/index.ts or ClickUpService.

Log Retrieval Procedures

• When initiated via npm run dev or npm start, console output serves as the log stream.
• If the server is managed by an MCP client (e.g., Claude Desktop), log files are typically captured by the client application. For Claude Desktop, potential locations include:
• Windows: %USERPROFILE%\AppData\Local\Claude\Logs\mcp\<server_name_and_id>\<process_id>.log (Path subject to client versioning)
• macOS: ~/Library/Logs/Claude/mcp/<server_name_and_id>/<process_id>.log (Path subject to client versioning)

Community Acknowledgment

Support for the continued maintenance and enhancement of this utility is appreciated via charitable contribution.

Licensing

Licensed under the MIT terms. Refer to the LICENSE artifact for full specifics.

Re-alignment fix for pipeline validation