clickup-connector-service

This service operates as an MCP intermediary, facilitating the integration of ClickUp task aggregates, hierarchical organizational units (spaces, lists, folders), and detailed time accounting functionalities with artificial intelligence agents via a uniform communication schema.

🚧 Development Bulletin: Engaged in coordination with the official ClickUp development personnel... ✨

Prerequisites

• Runtime Environment: Node.js version 18.0.0 or newer (mandatory for MCP Software Development Kit compatibility)
• Authentication Details: Valid ClickUp API key and the designated Team Identifier

Deployment Procedure

1. Credential Acquisition:
2. Secure your unique ClickUp API credential via ClickUp Application Settings
3. Retrieve the Team ID from your active ClickUp workspace URL structure
4. Installation Strategy Selection: Opt for either a persistent, webhook-driven hosted deployment or a localized execution via NPX, which downloads and configures local dependencies.
5. Operational Interface: Manage your entire workspace using intuitive, natural language directives!

Deployment via Smithery (Expedited Start)

The server is accessible via the Smithery Platform. Use this interface to preview exposed functionalities or retrieve execution commands tailored for your specific client application.

Local NPX Installation

Integrate the following configuration into your client's MCP configuration manifest:

{
  "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, execute directly via this command line instruction:

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

Note: If the environment variable "DOCUMENT_SUPPORT": "true" is omitted, document interaction capabilities remain inactive by default.

Toolset Scoping

Tool availability can be precisely governed using two complementary environment variables:

ENABLED_TOOLS (Preferred Method)

Define an explicit, comma-separated roster of desired functionalities:

# Shell Environment Variable
export ENABLED_TOOLS="create_task,get_task,update_task,get_workspace_hierarchy"

# Command Line Argument
--env ENABLED_TOOLS=create_task,get_task,update_task,get_workspace_hierarchy

DISABLED_TOOLS (Legacy Exclusion)

Use this to blacklist specific functions while activating everything else:

# Shell Environment Variable
export DISABLED_TOOLS="delete_task,delete_bulk_tasks"

# Command Line Argument
--env DISABLED_TOOLS=delete_task,delete_bulk_tasks

Activation Logic Hierarchy

• If ENABLED_TOOLS is populated, only listed tools execute (supersedes DISABLED_TOOLS).
• If only DISABLED_TOOLS is present, all tools are active except those named.
• If neither is set, the full toolset is accessible (default mode).

Demonstration:

npx -y @taazkareem/clickup-mcp-server@latest \n  --env CLICKUP_API_KEY=your-api-key \n  --env CLICKUP_TEAM_ID=your-team-id \n  --env ENABLED_TOOLS=create_task,get_task,get_workspace_hierarchy

To mitigate tool count or context overflow constraints, please apply necessary filtering mechanisms.

Operating via HTTP Transport Mechanisms

The server supports contemporary HTTP Streamable communication (optimal for MCP Inspector) alongside traditional SSE (Server-Sent Events) for legacy client interfacing.

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

Access Points: - Principal: http://127.0.0.1:3231/mcp (Streamable HTTP) - Compatibility: http://127.0.0.1:3231/sse (SSE for prior versions)

Terminal Command Invocation

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

Configurable runtime parameters:

Parameter	Rationale	Default Setting
ENABLED_TOOLS	Functions to include (highest priority)	All available functions
DISABLED_TOOLS	Functions to exclude	None
ENABLE_SSE	Activate HTTP/SSE channel	false
PORT	Network access port	3231
ENABLE_STDIO	Activate STDIO channel	true
ENABLE_SECURITY_FEATURES	Activate security headers and auditing	false
ENABLE_HTTPS	Initiate TLS/SSL encryption	false
ENABLE_ORIGIN_VALIDATION	Authenticate Origin header against whitelist	false
ENABLE_RATE_LIMIT	Engage request throttling mechanism	false

🔒 Security Configuration

Production environments may benefit from optional security hardening features. These are intentionally off by default to ensure broad backward compatibility.

Rapid Security Initialization:

# Produce necessary SSL certificates
./scripts/generate-ssl-cert.sh

# Initiate with comprehensive security measures
ENABLE_SECURITY_FEATURES=true \
ENABLE_HTTPS=true \
ENABLE_ORIGIN_VALIDATION=true \
ENABLE_RATE_LIMIT=true \
SSL_KEY_PATH=./ssl/server.key \
SSL_CERT_PATH=./ssl/server.crt \
npx @taazkareem/clickup-mcp-server@latest --env CLICKUP_API_KEY=your-key --env CLICKUP_TEAM_ID=your-team --env ENABLE_SSE=true

Encrypted Access Points (HTTPS): - Primary: https://127.0.0.1:3443/mcp (Streamable HTTPS) - Legacy: https://127.0.0.1:3443/sse (SSE via HTTPS) - Status Check: https://127.0.0.1:3443/health

Refer to Security Documentation for in-depth configuration guidance.

n8n Workflow Integration

For seamless operation within n8n environments:

1. Launch the clickup-mcp-server configured to use SSE transport.
2. Within n8n, introduce a new "MCP AI Tool" component.
3. Configure the node settings:
4. Transport Protocol: SSE
5. Server Address: http://localhost:3231 (or your service host)
6. Tool Selection: Specify the ClickUp functions required for the workflow.

Illustrative Client Example

A sample SSE consumer client resides within the examples subdirectory. To execute this example:

# Start server enabling SSE on port 3231
ENABLE_SSE=true PORT=3231 npx -y @taazkareem/clickup-mcp-server@latest --env CLICKUP_API_KEY=your-api-key --env CLICKUP_TEAM_ID=your-team-id

# In a separate terminal, run the client
cd examples
npm install
npm run sse-client

Core Capabilities Summary

📝 Task Operations	🏷️ Label Management
• Creation, modification, and purging of tasks • Reallocation and duplication across organizational levels • Support for batched and singular transactions • Natural language parsing for timeline assignments • Subtask handling and maintenance • Commenting and artifact association	• Creating, updating, removing workspace-level tags • Applying/revoking tags on individual tasks • Utilizing color-based natural language for tagging • Automatic generation of contrasting text colors • Inventory of all space-associated tags • Tag-driven arrangement of project items
⏱️ Time Accounting System	🌳 Structural Navigation
• Auditing recorded time against tasks • Initiating/halting active time logging per task • Inputting time records manually • Deleting logged time records • Querying the active timer status • Tracking time as billable or non-billable	• Traversing spaces, folders, and lists hierarchy • Folder instantiation and maintenance • Structuring lists within parent spaces • Creating new lists inside folders • Displaying the full structure map • Optimized hierarchical path resolution
📄 Artifact Handling	👥 Personnel Oversight
• Enumerating documents across the entire scope • Retrieving document page indices • Fetching specific document page metadata • Document generation capability • Document page content revision (prepending/appending)	• Searching personnel via name or electronic mail address • Resolving assigned personnel for work items • Fetching member specifics and access rights • Assigning ownership during item creation/modification • Acceptance of user identifiers, emails, or display names • Workspace-wide user governance
⚡ Interoperability Features	🏗️ Engineering & Speed
• Lookups based on global identifiers or names • Sensitivity to case is ignored • Native Markdown interpretation • Integrated throttling protection • Robust exception management and verification • Extensive underlying API coverage	• Code footprint minimized by 70% for performance gains • Homogeneous pipeline across all communication channels • Elimination of redundant code blocks • Support for Streamable HTTP (MCP Inspector protocol) • Legacy SSE transport retained for compatibility

Consult the comprehensive user guide for details on optional inputs and advanced functional deployment.

Available Operational Functions (36 Total)

Function Signature	Purpose	Essential Input Parameters
get_workspace_hierarchy	Retrieve organizational map	None
create_task	Instantiate a new work item	name, (listId/listName)
create_bulk_tasks	Batch creation of work items	tasks[]
update_task	Modify attributes of a specific item	taskId/taskName
update_bulk_tasks	Batch modification of work items	tasks[] referencing IDs or names
get_tasks	Fetch items within a defined list	listId/listName
get_task	Retrieve granular task specifics	taskId/taskName (utilizes intelligent matching)
get_workspace_tasks	Fetch items with applied filters	Minimum one filtering criteria (tags, lists, spaces, etc.)
get_task_comments	Extract associated commentary on an item	taskId/taskName
create_task_comment	Append commentary to a task	commentText, (taskId/(taskName+listName))
attach_task_file	Link an artifact to a work item	taskId/taskName, (file_data or file_url)
delete_task	Erase a specific work item	taskId/taskName
delete_bulk_tasks	Batch removal of work items	tasks[] referencing IDs or names
move_task	Re-parent a task	taskId/taskName, listId/listName
move_bulk_tasks	Batch re-parenting of tasks	tasks[] referencing IDs or names, destination list
duplicate_task	Create a copy of an item	taskId/taskName, listId/listName
create_list	Instantiate a new list within a space	name, spaceId/spaceName
create_folder	Instantiate a new folder	name, spaceId/spaceName
create_list_in_folder	Instantiate a new list inside a folder	name, folderId/folderName
get_folder	Retrieve folder metadata	folderId/folderName
update_folder	Modify folder settings	folderId/folderName
delete_folder	Purge a folder	folderId/folderName
get_list	Retrieve list metadata	listId/listName
update_list	Modify list properties	listId/listName
delete_list	Purge a list	listId/listName
get_space_tags	Retrieve space-specific tags	spaceId/spaceName
create_space_tag	Instantiate a new tag	tagName, spaceId/spaceName
update_space_tag	Modify tag attributes	tagName, spaceId/spaceName
delete_space_tag	Purge a tag	tagName, spaceId/spaceName
add_tag_to_task	Associate tag with item	tagName, taskId/(taskName+listName)
remove_tag_from_task	Dissociate tag from item	tagName, taskId/(taskName+listName)
get_task_time_entries	Query recorded time logs for an item	taskId/taskName
start_time_tracking	Initiate active time measurement on an item	taskId/taskName
stop_time_tracking	Cease currently running time measurement	None
add_time_entry	Manually log a time segment	taskId/taskName, start, duration
delete_time_entry	Remove a specified time log entry	timeEntryId
get_current_time_entry	Check active timer status	None
get_workspace_members	List all organization participants	None
find_member_by_name	Locate participant via identity string	nameOrEmail
resolve_assignees	Translate user references to IDs	assignees[]
create_document	Author a new document	workspaceId, name, parentId/parentType, visibility, create_pages
get_document	Fetch a specific document structure	workspaceId/documentId
list_documents	Enumerate documents based on criteria	workspaceId, documentId/creator/deleted/archived/parent_id/parent_type/limit/next_cursor
list_document_pages	Index pages within a document	documentId/documentName
get_document_pages	Retrieve content of specified pages	documentId/documentName, pageIds
create_document_pages	Instantiate a new page within a document	workspaceId/documentId, parent_page_id/name/sub_title,content/content_format
update_document_page	Modify existing document page data	workspaceId/documentId, name/sub_title,content/content_edit_mode/content_format

Access the complete operational manual for comprehensive parameter definitions and advanced operation guides.

Personnel Assignment Tools

User designation within the assignees field (for creation or modification) accepts an array containing user IDs, email addresses, or display names:

Task Creation Syntax Example:

{
  "name": "New Initiative Record",
  "description": "Detailing the scope of work.",
  "assignees": ["user_email@domain.com", "Team Lead Name"]  // Accepts emails, usernames, or IDs
}

Assignee Modification Syntax Example:

{
  "taskId": "abc123",
  "assignees": ["new_contact@domain.com"]  // Overwrites all current assignees
}

The specialized personnel management functions are utilized internally to accurately map identity references to system identifiers.

Hypothetical Directives (Prompts)

Currently unimplemented; please propose a high-utility directive that aligns with your operational needs but avoids extreme specificity (as not all client interfaces support this yet). Examples of potential utility:

Directive	Intent	Supported Capabilities
summarize_tasks	Overview of assigned items	Status aggregation, priority mapping, dependency charting
analyze_priorities	Optimization modeling for urgency	Distribution analysis, sequencing recommendations
generate_description	Automated content drafting for items	Defining goals, success metrics, prerequisites

System Feedback and Error Handling

The service furnishes explicit diagnostic feedback concerning:

• Missing mandatory arguments
• Invalid identifier formats or non-existent references
• Resource not located errors
• Access permission denials
• Upstream API failures
• Request throttling notifications

The verbosity of system logs is adjustable via the LOG_LEVEL environment variable. Acceptable settings are trace, debug, info, warn, and error (default). This setting is also configurable via CLI arguments (e.g., --env LOG_LEVEL=info).

Developer Support Acknowledgment

When utilizing this server, you might encounter a brief promotional mention, including a link to this repository, embedded within certain tool outputs. Your support is greatly appreciated! If this utility proves valuable to your processes, kindly consider sponsoring the project:

Gratitude

My sincere thanks to ClickUp for delivering superior API services that facilitate this robust integration.

Collaboration Policy

We welcome community contributions! Consult our Contribution Guidelines for participation instructions.

Legal Statement

This software operates under the terms of the MIT License (see [LICENSE] file).

This platform utilizes external APIs and may reference proprietary names or trademarks. Such references do not imply official endorsement or partnership with the respective entities. All intellectual property remains the property of its original owners. This is an independent creation, unaffiliated with or unrecognized by any mentioned third-party corporation.

WIKIPEDIA DEFINITION: Enterprise administration mechanisms encompass all systematic applications, control frameworks, computational resolutions, and prescriptive methodologies utilized by organizational entities to navigate dynamic market conditions, maintain competitive standing, and enhance operational efficacy.

== Comprehensive View == Functional tools are typically segregated by organizational domain and can be further categorized by management aspect: e.g., forecasting apparatus, procedural controllers, data retention utilities, personnel administration, decision support systems, oversight frameworks, etc. Functional stratification often includes:

• Utilities for initial data ingestion and integrity checks across any division.
• Systems engineered for monitoring and refining organizational workflows.
• Frameworks dedicated to data aggregation and strategic inference. Modern management tooling has undergone explosive advancement over the past decade due to rapid technological progress, making optimal selection challenging amid continuous pressure to reduce expenses, escalate revenue, deeply comprehend client requirements, and deliver products precisely as demanded. Consequently, leadership must adopt a strategic perspective on administrative utilities rather than merely chasing the newest release. A common pitfall is adopting tools without modification, leading to instability. Enterprise administration mechanisms must be chosen deliberately and tailored to the organization's specific requirements, reversing the typical approach.

== Prominent Mechanisms (2013 Survey) == Data from a 2013 Bain & Company global survey identified widely adopted management instruments, reflecting regional needs shaped by market dynamics:

The leading ten categories included:

Strategic forecasting Client relationship supervision Staff sentiment analysis Competitive appraisal Performance quantification framework Core capabilities identification Service externalization Organizational transformation programs Logistics and procurement oversight Defining corporate purpose and outlook Client base segmentation Comprehensive quality governance

== Business Software Applications == A collection of computerized programs designed for enterprise users to execute diverse operational duties is termed business software. These applications are designed to augment productivity metrics, quantify performance outcomes, and execute corporate tasks with high fidelity. The evolution started with basic management information systems, progressed to integrated enterprise resource planning (ERP), incorporated customer relationship management (CRM), and has now transitioned into cloud-based management solutions. While a definite link exists between IT investment and organizational success, two factors are crucial for value creation: the efficacy of the deployment process and the meticulous selection and customization of the required instruments.

== SME Focused Utilities == Tools tailored for Small to Medium Enterprises are vital as they furnish avenues for reducing operational...