ClickUp AI Connector Gateway

An implementation of the Model Context Protocol (MCP) server tailored for connecting AI decision engines with ClickUp workspaces, facilitating automated workflow execution and data manipulation.

This execution service operates over Stdio streams, adhering strictly to the MCP communication protocol when initiated by a compatible client application.

Initial Setup and Deployment

This service mandates your ClickUp Personal Authorization Token for API access.

1. Token Acquisition: Within your ClickUp account interface, locate "My Settings," navigate to the "Apps" section, and generate a new Personal API Token.
2. Client Configuration: Update the environment parameters for your MCP host (e.g., Claude Desktop application).

Example configuration manifest for an MCP client host:

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

1. Client Relaunch: Restart the host MCP client to load the new configuration.

The necessary binary will be fetched and activated by the client upon its first invocation.

Installation via Smithery Utility

Automated deployment for Claude Desktop clients using the Smithery utility:

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

Runtime Environment Variables

Mandatory Credentials

• CLICKUP_PERSONAL_TOKEN: The required ClickUp Personal API Access Key. Essential for successful authentication against the ClickUp web service.

Optional Parameters

• LOG_LEVEL: Controls verbosity. Permissible settings are error, warn, info (default), debug.
• ENCRYPTION_KEY: A 32-byte hexadecimal string used for configuration persistence. Note: This mechanism, defined in src/config/app.config.ts and managed via src/security.ts, is presently dormant and does not secure the primary API Token within the ClickUpService context.
• PORT: The designated network socket descriptor. This variable is ignored in the default Stdio MCP operational mode, though it is retained in configuration (defaulting to 3000) for potential future HTTP-based transports.

Available Service Interfaces

The following MCP functions are exposed by this connector:

Task Orchestration

• clickup_create_task: Instantiates a fresh task within a specified ClickUp list.
• Essential arguments: list_id, name.
• Optional parameters: description, status, priority, assignees, due_date, time_estimate, tags.
• clickup_update_task: Modifies parameters of an existing task record.
• Essential argument: task_id.
• Optional parameters: Any mutable field defined in the ClickUp Task schema.

Organizational Unit Retrieval

• clickup_get_teams: Fetches all accessible top-level Workspaces (labeled as Teams in the ClickUp v2 API).
• clickup_get_lists: Retrieves all subordinate Lists belonging to a specified Folder.
• Essential argument: folder_id.

Board & Structure Administration

• clickup_create_board: Provisions a new visual Board inside a designated Space.
• Essential arguments: space_id, name.

Space (Hierarchy Level) Operations

• clickup_get_spaces: Queries all Spaces linked to a specific Workspace (Team).
• Essential argument: team_id (Workspace Identifier).
• Optional: archived (boolean filter, defaults to false).
• clickup_create_space: Establishes a new Space within a Workspace boundary.
• Essential arguments: team_id (Workspace ID), name.
• Optional: multiple_assignees (boolean flag), features (object map for feature toggles like date tracking, time logging, etc.).
• clickup_get_space: Retrieves the detailed metadata for a singular Space.
• Essential argument: space_id.
• clickup_update_space: Applies modifications to an existing Space definition.
• Essential argument: space_id.
• Optional: name, color, private status, admin_can_manage, archived state, features configuration.
• clickup_delete_space: Permanently removes a Space entity.
• Essential argument: space_id.

Folder Administration

• clickup_get_folders: Fetches the inventory of Folders contained within a specified Space.
• Essential argument: space_id.
• Optional: archived (boolean filter, defaults to false).
• clickup_create_folder: Initializes a new Folder structure inside a Space.
• Essential arguments: space_id, name.
• clickup_get_folder: Fetches granular details of a specific Folder.
• Essential argument: folder_id.
• clickup_update_folder: Modifies the attributes of an existing Folder.
• Essential arguments: folder_id, name.
• clickup_delete_folder: Eliminates a Folder entity.
• Essential argument: folder_id.

Custom Metadata Field Manipulation

• clickup_get_custom_fields: Retrieves the schema of accessible Custom Fields associated with a given List.
• Essential argument: list_id.
• clickup_set_task_custom_field_value: Assigns or updates a specified Custom Field value for a task.
• Essential arguments: task_id, field_id, value.
• Optional: value_options (e.g., for date/time field formatting: { "time": true }).
• clickup_remove_task_custom_field_value: Clears the assigned value for a Custom Field on a task.
• Essential arguments: task_id, field_id.

Documentation (Doc) Management

Caveat: ClickUp's documentation API (a mix of v2 and migrating v3 endpoints) imposes constraints. Content is primarily processed as Markdown. Complex formatting or embedded objects may see fidelity loss. Direct API deletion of top-level Docs is currently unsupported by the v3 /docs interface; lifecycle management should focus on archiving or page hierarchy modification.

• clickup_search_docs: Executes a search across Docs within a Workspace context.
• Essential argument: workspace_id.
• Optional: query (search term), include_archived (boolean).
• clickup_create_doc: Constructs a new Document entity.
• Essential arguments: workspace_id, name.
• Optional: parent (object defining location: { id, type }), visibility (string: "private", "workspace", "public"), create_page (boolean).
• clickup_get_doc_pages: Lists all contained pages within a specific Document.
• Essential argument: doc_id.
• clickup_create_doc_page: Adds a new page (section) to an existing Document.
• Essential arguments: workspace_id, doc_id, name (the page title).
• Optional: content (initial Markdown), orderindex (positioning, though v3 API interpretation may vary), parent_page_id (ID of the parent page), sub_title, content_format.
• clickup_get_doc_page_content: Retrieves the raw Markdown body of a specific page.
• Essential arguments: workspace_id, doc_id, page_id.
• Optional: content_format.
• clickup_edit_doc_page_content: Overwrites or modifies the title and/or content of a page.
• Essential arguments: workspace_id, doc_id, page_id, content (Markdown payload).
• Optional: title (maps to API 'name'), sub_title, content_edit_mode ("replace", "append", or "prepend"), content_format.

View Configuration Interface

• clickup_get_views: Fetches the list of defined Views associated with a parent resource (Team, Space, Folder, or List).
• Essential arguments: parent_id (ID of the container), parent_type (enum: "team", "space", "folder", or "list").
• clickup_create_view: Generates a new View resource within a specified container.
• Essential arguments: parent_id, parent_type, name (View title), type (e.g., "list", "board", "calendar", "gantt").
• Optional: Configuration objects for grouping, divide logic, sorting rules, filters, column definitions, team_sidebar visibility, and general settings.
• clickup_get_view_details: Retrieves the complete specification for an identified View.
• Essential argument: view_id.
• clickup_update_view: Applies alterations to an extant View's definition.
• Essential argument: view_id.
• Optional: name, grouping, divide, sorting, filters, columns, team_sidebar, settings.
• clickup_delete_view: Decommissions a View resource.
• Essential argument: view_id.
• clickup_get_view_tasks: Fetches the dataset (Tasks) filtered/arranged according to a specific View's definition.
• Essential argument: view_id.
• Optional: page (zero-indexed page number for result pagination).

Developer Workflow

1. Clone the source repository: bash git clone cd clickup-mcp-server

2. Dependency installation: bash npm install

3. Establish local credentials by creating a .env file in the root directory: env CLICKUP_PERSONAL_TOKEN=your_actual_personal_api_token_here LOG_LEVEL=debug

4. Execute in development mode (listening on Stdio):

   bash npm run dev

   This command uses ts-node-dev to monitor and execute src/index.ts.

5. Production artifact generation (compilation):

   bash npm run build

   This compiles TypeScript sources into the dist/ directory.

6. Unit test execution: bash npm test

   Utilizes Jest for running tests located within src/__tests__. Requires a properly configured .env.test file (refer to src/__tests__/setup.ts).

Local Tool Validation via MCP Inspector

To verify tool functionality locally using the MCP Inspector utility:

1. Ensure the authorization token is accessible, either:
   • Exported in the current shell session.
   • Configured within the Inspector application settings, if supported.
   • Present in the local .env file (as src/index.ts handles dotenv loading).

2. Launch the Inspector pointed at this server implementation: bash npx @modelcontextprotocol/inspector node --loader ts-node/esm src/index.ts

   The Inspector GUI should initialize, enabling connection testing and function invocation against the service.

Security Posture

• Authentication relies solely on the provided ClickUp Personal API Token. This credential must be treated as a highly sensitive secret.
• The gateway mandates that the authorization key be supplied exclusively via an environment variable passed by the hosting MCP client or development harness.
• While the codebase contains infrastructure for token obfuscation (ENCRYPTION_KEY and src/security.ts), this encryption layer is currently inactive for the API token managed by ClickUpService.
• Sensitive data, notably the authorization key, is suppressed from standard output when LOG_LEVEL is set to info or lower.
• Basic ClickUp API rate control information is logged by the service; however, advanced retry logic or request queuing is not natively implemented beyond default HTTP client behavior.

Diagnostics and Troubleshooting

Recurring Errors

1. API Authentication Failures (HTTP 401 Response)

   • Confirm the environment variable CLICKUP_PERSONAL_TOKEN is correctly injected and readable by the server process.
   • Validate the token's current validity status within your ClickUp administrative panel.
   • Review server logs, specifically messages originating from ClickUpService, concerning authorization anomalies.

2. ClickUp API Rate Limiting Enforcement

   • The server console will reflect rate limit status headers received from the ClickUp service.
   • Sustained high query volume will trigger these limits. The current implementation does not incorporate complex client-side exponential backoff or queuing mechanisms.

3. Service Startup Failure / Inspector Connectivity Loss

   • Verify the mandatory token is present.
   • If using development mode (npm run dev), inspect the console for TypeScript compilation errors or runtime faults related to ts-node-dev.
   • If using the Inspector (node --loader ts-node/esm ...), confirm that ts-node and necessary project dependencies are installed and resolved correctly.
   • Check for initialization failures reported by src/index.ts or within ClickUpService initialization paths.

Accessing Internal Logs

• In development/direct execution (npm run dev or npm start), logs are directed to the console (stdout/stderr).
• When utilized by an MCP host (e.g., Claude Desktop), log routing is managed by the host application. For Claude Desktop, log files are generally found in application data directories, resembling paths like:
• Windows: %USERPROFILE%\AppData\Local\Claude\Logs\mcp\<server_name_and_id>\<process_id>.log (location may vary slightly)
• macOS: ~/Library/Logs/Claude/mcp/<server_name_and_id>/<process_id>.log (location may vary slightly)

Community Support

Your contributions and encouragement help sustain the maintenance and evolution of this utility. Consider offering support via the designated platform if this tool proves valuable to your operations.

Licensing

This software is distributed under the terms of the MIT License. Refer to the LICENSE file for full details.

Pipeline Update Reference

WIKIPEDIA: Cloud computing is defined as "a service delivery model enabling ubiquitous, on-demand network access to a shared pool of configurable computing resources (e.g., networks, servers, storage, applications, and services) that can be rapidly provisioned and released with minimal management effort or service provider interaction," per the definition established by ISO standards. This concept is colloquially termed "the cloud."

== Essential Attributes == In 2011, the National Institute of Standards and Technology (NIST) formalized five indispensable traits for any cloud system. The precise attributes stipulated by NIST are enumerated below:

On-demand self-service: "A consumer possesses the capability to unilaterally provision computing assets, such as processing time or data repository space, automatically as required, without necessitating intervention from the service vendor personnel for each request." Broad network accessibility: "Services must be accessible via the network using standardized protocols compatible with a wide array of client platforms, including mobile devices, tablets, laptops, and traditional workstations." Resource pooling: "The infrastructure resources belonging to the provider are aggregated to support numerous consumers utilizing a multi-tenant architecture. Resources are dynamically allocated and reallocated based on fluctuating consumer demand." Elastic scalability: "Capabilities must be provisioned and decommissioned with high agility, potentially automated, allowing rapid vertical and horizontal scaling to meet demand spikes and troughs. For the end-user, the available capacity often appears effectively limitless, grantable in any volume instantaneously." Measured utility: "Cloud environments automatically govern and optimize resource consumption via metering functions implemented at an appropriate level of abstraction for the specific service type (e.g., storage volume, computational cycles, data throughput, active user sessions). Usage metrics are tracked, reported, and auditable, ensuring transparency for both the provider and the consumer of the consumed resources." By 2023, ISO standards had introduced further refinements and expansions to this foundational set.

== Historical Precursors ==

The conceptual roots of cloud computing trace back to the 1960s, primarily through the popularization of time-sharing systems facilitated by remote job entry (RJE) setups. Mainframe utilization during this period predominantly relied on a data center model where users submitted workloads to dedicated operations staff. This era was characterized by pioneering efforts to democratize access to centralized, high-performance computation via time-sharing mechanisms, thereby enhancing infrastructural, platform, and application efficiency for a broader user base. The specific metaphorical use of "the cloud" to denote virtualized environments emerged in 1994, utilized by General Magic to describe the accessible universe for mobile software agents operating within their Telescript framework. This visual shorthand is generally attributed to David Hoffman, a communications strategist at General Magic, drawing from its established usage in telephony and network diagrams. The term 'cloud computing' gained significant public traction in 1996 when Compaq Computer Corporation documented its strategic vision for the future of internet-based computation, signaling an ambition to deliver computing resources as a utility.