clickup-service-gateway

This Model Context Protocol (MCP) infrastructure serves as a robust bridge, enabling intelligent agents to issue commands against ClickUp entities—specifically tasks, organizational units (spaces, folders, lists), time records, and associated documentation—using a normalized protocol.

🚀 Latest Release: Version 0.7.2 incorporates full capabilities for granular Time Tracking administration and comprehensive Document Handling modules.

Deployment Prerequisites

1. Secure Authorization Credentials:
2. Retrieve your unique ClickUp API authorization token via ClickUp Developer Settings
3. Determine your designated Team Identifier from your primary ClickUp workspace URL.
4. Installation Method Selection:
5. Opt for the cloud-hosted deployment (which utilizes webhooks for real-time updates) OR the local NPX installation (which fetches dependencies and installs to a designated local directory).
6. Initiate interaction using conversational instructions.

Smithery Rapid Deployment

The gateway is centrally hosted on Smithery. This dashboard allows for interactive tool previewing and easy command copying compatible with your specific client application setup.

Local NPX Deployment

Integrate this configuration into your client's MCP configuration manifest (JSON):

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

Alternatively, utilize the following direct execution command:

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

Note: If the environmental variable "DOCUMENT_SUPPORT": "true" is omitted, document features default to inactive status.

Furthermore, the DISABLED_TOOLS environment variable or the corresponding --env DISABLED_TOOLS argument permits the quiescing of specific functionalities. Supply a comma-separated enumeration of tool identifiers you wish to deactivate (e.g., create_task,delete_task).

It is recommended to disable unnecessary tools if you encounter constraints related to tool count or context window limitations.

Core Functionality Set

📝 Task Administration	🏷️ Metadata Tagging
• Initialization, modification, and removal of tasks • Relocation and duplication across organizational boundaries • Support for both singular and batch operations • Date assignment (start/due) via linguistic interpretation • Creation and oversight of subordinate tasks • Comment injection and file attachment management	• Creation, modification, and deletion of space-level tags • Assignment and dissociation of tags from tasks • Utilization of natural language directives for color coding • Integrated logic for generating complementary foreground colors • Retrieval of all defined space tags • Cross-workspace task sorting based on assigned tags
⏱️ Temporal Resource Logging	🌳 Hierarchical Structure Management
• Auditing recorded time expenditures for tasks • Initiating/halting active time measurement per task • Injecting arbitrary time entries manually • Erasing recorded time logs • Querying the currently active timer status • Delineation of billable versus non-billable durations	• Traversal of spaces, folders, and lists within the hierarchy • Folder creation and structure maintenance • List arrangement within parent spaces • Establishing new lists inside defined folders • Visualization of the entire workspace map • Streamlined path resolution capabilities
📄 Document Assets	⚡ System Interoperability Features
• Comprehensive listing of all documents across the entire workspace • Retrieval of specific document page manifests • Detailed inspection of individual document page content • Document genesis operations • Document page content modification (appending or prepending text)	• Entity lookups based on canonical name or system ID, globally applicable • Tolerance for case-insensitive string matching • Native support for Markdown formatting structures • Integrated mechanism for handling API request velocity limits • Robust error capture and input validation routines • Extensive coverage mapping of underlying ClickUp API endpoints

Refer to the comprehensive documentation module for optional parameters and advanced operational techniques.

Available Operational Modules

Module Identifier	Function Description	Mandatory Inputs
get_workspace_hierarchy	Retrieve the structural map of the environment	None
create_task	Formulate a new task item	name, (listId/listName)
create_bulk_tasks	Generate a collection of task items	tasks[]
update_task	Institute modifications on an existing task	taskId/taskName
update_bulk_tasks	Apply batch modifications to tasks	tasks[] specified by IDs or names
get_tasks	Fetch tasks contained within a specific list	listId/listName
get_task	Retrieve the full specification of one task	taskId/taskName (with intelligent context resolution)
get_workspace_tasks	Acquire tasks subject to specific constraints	Must provide at least one filtering criterion (e.g., tags, list_ids, space_ids, etc.)
get_task_comments	Extract associated commentary for a task	taskId/taskName
create_task_comment	Append new commentary to a task	commentText, (taskId/(taskName+listName))
attach_task_file	Bind external data/file to a task	taskId/taskName, (file_data or file_url)
delete_task	Permanently retire a task	taskId/taskName
delete_bulk_tasks	Initiate bulk task decommissioning	tasks[] specified by IDs or names
move_task	Reassign a task to a new container	taskId/taskName, listId/listName
move_bulk_tasks	Facilitate mass task relocation	tasks[] by ID/name, target list identifier
duplicate_task	Produce an exact replica of a task	taskId/taskName, listId/listName
create_list	Establish a new list within a space	name, spaceId/spaceName
create_folder	Instantiate a new folder container	name, spaceId/spaceName
create_list_in_folder	Generate a list nested within a folder	name, folderId/folderName
get_folder	Obtain detailed folder attributes	folderId/folderName
update_folder	Revise attributes of a folder	folderId/folderName
delete_folder	Remove a folder structure	folderId/folderName
get_list	Retrieve granular list information	listId/listName
update_list	Adjust parameters defining a list	listId/listName
delete_list	Archive or remove a list	listId/listName
get_space_tags	Query existing tags associated with a space	spaceId/spaceName
create_space_tag	Define a novel tag within a space	tagName, spaceId/spaceName
update_space_tag	Modify the characteristics of an established tag	tagName, spaceId/spaceName
delete_space_tag	Decommission a space tag	tagName, spaceId/spaceName
add_tag_to_task	Apply a tag categorization to a task	tagName, taskId/(taskName+listName)
remove_tag_from_task	Detach a tag from task association	tagName, taskId/(taskName+listName)
get_task_time_entries	Fetch all time logs linked to a task	taskId/taskName
start_time_tracking	Commence active time measurement on a task	taskId/taskName
stop_time_tracking	Terminate any currently active time session	None
add_time_entry	Log a retrospective time segment	taskId/taskName, start, duration
delete_time_entry	Erase a specific time record entry	timeEntryId
get_current_time_entry	Check the status of the active timer	None
create_document	Generate a new documentation artifact	workspaceId, name, parentId/parentType, visibility, create_pages
get_document	Retrieve the root details of a document	workspaceId/documentId
list_documents	Enumerate the collection of documents	workspaceId, documentId/creator/deleted/archived/parent_id/parent_type/limit/next_cursor
list_document_pages	Obtain the manifest of pages within a document	documentId/documentName
get_document_pages	Fetch the content structure of designated pages	documentId/documentName, pageIds
create_document_pages	Construct a new page within a document	workspaceId/documentId, parent_page_id/name/sub_title,content/content_format
update_document_page	Modify the body or metadata of a page	workspaceId/documentId, name/sub_title,content/content_edit_mode/content_format

Consult the canonical documentation resource for exhaustive details on optional arguments and advanced usage paradigms.

Predefined Conversational Templates (Prompts)

Currently, direct execution of high-level prompts is not universally implemented across all client applications. If a Prompt construct would significantly enhance your specific operational pipeline, please submit a feature request specifying the workflow benefit (avoiding excessive specificity).

Template Name	Core Objective	Supported Output Characteristics
summarize_tasks	Comprehensive task inventory report	Status aggregates, priority distribution, dependency mapping
analyze_priorities	Optimization analysis for task sequencing	Distribution heatmaps, chronological ordering suggestions
generate_description	Automated formulation of task narratives	Objective statements, success criteria definition, dependency articulation

Operational Feedback Mechanisms

The gateway furnishes explicit error diagnostics for the following conditions:

• Absence of mandatory configuration parameters
• Verification failure of provided identifiers or nomenclature
• Non-existence of referenced entities
• Authorization or access privilege violations
• Upstream API communication failures
• Exceeded request throughput thresholds

The logging verbosity is governed by the LOG_LEVEL environment parameter. Permitted settings include trace, debug, info, warn, and error (the system default). This setting can also be applied via command line, for example: --env LOG_LEVEL=info.

Developer Stewardship

While utilizing this service, you might occasionally encounter a discrete sponsor notification containing a hyperlink back to this repository. Support for the project is deeply appreciated if you find this integration valuable:

Credits and Affiliations

Heartfelt gratitude extended to ClickUp for providing the high-quality API and infrastructure that underpins this integration capability.

Community Contribution Guidelines

We welcome external contributions! Please consult our Contribution Protocol Document for detailed instructions.

Legal Stipulations

This software package is governed under the stipulations of the MIT License; review the LICENSE file for comprehensive terms.

Liability Disclaimer

This application relies on external, third-party Application Programming Interfaces and may reference proprietary trademarks or branding belonging to external entities. The utilization of these APIs or references does not imply any formal association, sponsorship, or endorsement by the respective corporations. All trademarks and brand names remain the exclusive property of their legitimate owners. This project constitutes an independent development effort and carries no official affiliation or sponsorship relationship with any mentioned external organization. WIKIPEDIA: XMLHttpRequest (XHR) is an API in the form of a JavaScript object whose methods transmit HTTP requests from a web browser to a web server. The methods allow a browser-based application to send requests to the server after page loading is complete, and receive information back. XMLHttpRequest is a component of Ajax programming. Prior to Ajax, hyperlinks and form submissions were the primary mechanisms for interacting with the server, often replacing the current page with another one.

== Historical Context == The underlying concept for XMLHttpRequest was conceptualized in the year 2000 by the engineering team at Microsoft Outlook. This concept was subsequently actualized within the Internet Explorer 5 browser release (1999). Nonetheless, the initial method invocation did not employ the 'XMLHttpRequest' identifier; rather, developers instantiated objects via ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). Since the release of Internet Explorer 7 (2006), universal browser compatibility with the XMLHttpRequest identifier has been established. The XMLHttpRequest identifier has since solidified its position as the convention standard across all major browser environments, including Mozilla’s Gecko rendering engine (2002), Safari version 1.2 (2004), and Opera version 8.0 (2005).

=== Standardization Trajectory === The World Wide Web Consortium (W3C) formally issued a Working Draft specification for the XMLHttpRequest object on April 5, 2006. On February 25, 2008, the W3C published the Level 2 specification update. Level 2 introduced crucial methods for monitoring transaction progress, enabling cross-domain data exchanges, and processing raw byte streams. By the conclusion of 2011, the Level 2 enhancements were integrated into the primary specification document. In late 2012, development stewardship transitioned to the WHATWG, which now maintains a dynamic document utilizing the Web IDL specification language.

== Practical Application == Executing a network transaction using XMLHttpRequest typically involves a defined sequence of programming actions.

1. Instantiate the XMLHttpRequest object by invoking its constructor:
2. Invoke the "open" method to define the request method (GET, POST, etc.), specify the target resource endpoint, and select either synchronous or asynchronous execution mode:
3. For asynchronous operations, install an event listener callback function designed to signal state transitions:
4. Commence the transmission of the request payload by calling the "send" method:
5. Monitor and react to state changes within the established event listener. Upon successful receipt of response data from the server, it resides in the "responseText" attribute by default. When the processing cycle completes, the object transitions to state 4, the final "done" state. Beyond these fundamental steps, XMLHttpRequest offers extensive configuration options for request handling and response parsing. Custom header fields can be prepended to the outbound request to instruct the server on fulfillment requirements, and data can be uploaded via the argument provided to the "send" call. The server response stream can be deserialized from JSON format into immediately usable JavaScript structures, or processed incrementally as data arrives, bypassing the wait for the complete text block. Furthermore, the operation can be manually terminated prematurely or configured to fail if completion deadlines are not met.