Enhanced ClickUp Interaction Platform (MCP Server Fork)

This repository presents a significantly augmented iteration of the initial ClickUp MCP Server, originally developed by TaazKareem.

Significant Feature Expansion and Structural Overhaul

This modernized fork introduces substantial new capabilities and applies significant architectural refinements to the baseline implementation:

Novel Functionality Introduction

Advanced Task Relationship Management API

• Inter-Task Dependencies: Full lifecycle management for establishing prerequisites between discrete tasks.
• Mechanism to define required predecessors for task commencement.

• Capability to nullify dependency links upon resolution.

• Task Cross-Referencing (Links): Functionality to associate related tasks without imposing sequential prerequisites.

• Establish explicit relational pointers between items.

• Dissolve these informational links when relevance ceases.

• Metadata Tagging System: Support for applying descriptive tags for enhanced organizational grouping.

• Addition and removal of arbitrary tags to tasks.

• Comprehensive Commenting Subsystem: Robust interface for handling all tiers of task communication.

• Operations for reading and injecting remarks on individual tasks.
• Support for List-level annotations.
• Engagement with remarks within designated Chat Views.
• Native handling of conversational threads and replies.
• Utilities for modifying or deleting existing commentary records.

Checklist Management Module

• Task-Bound Checklists: System for defining structured to-do lists nested within tasks.
• Creation of procedural outlines or sub-task enumerations.
• Editing of checklist titles and adjustment of the sequence order.

• Removal of entire checklist containers.

• Checklist Item Granularity Control: Detailed manipulation of individual checklist elements.

• Functionality to instantiate new items (steps/subtasks).
• Updating of item descriptions, assignment ownership, or completion status.
• Support for hierarchical (nested) checklist item structures.
• Deletion of specific items upon completion or obsolescence.

Architectural Refinements

We have systematically modularized the codebase to enhance long-term maintainability:

1. Decoupled Service Architecture:
2. Isolation of the core ClickUp API interaction logic from feature-specific handlers.
3. Introduction of specialized service classes, each adhering to single responsibility principles.

4. Resulting in cleaner structure and easier debugging/extension.

5. Strict Type-Safe Development:

6. Substantial enrichment of TypeScript interfaces covering all external API contracts.
7. Segregation of domain-specific type definitions into dedicated modules.

8. Significant improvements in IDE assistance (autocomplete) and static error catching.

9. Standardized Tool Integration Pipeline:

10. Establishment of a dedicated abstraction layer specifically for MCP tool registration.
11. Centralized registry for tool metadata and execution handlers.

12. Drastically reduced friction when incorporating novel functionality.

13. Streamlined Deployment Assets:

14. Integration of Railway deployment manifest files.
15. Provision of standardized environment configuration templates.
16. Simplification of the environment bootstrapping process.

Pre-existing Capabilities

The foundation of the server continues to support essential operations, including:

• Navigation across the entire Workspace hierarchy.
• Creation and modification of discrete tasks.
• Management tasks related to Lists and Folders.
• Utilities for task relocation and cloning.
• Advanced searching and data filtering protocols.

Deployment and Initialization

Local Environment Setup

1. Clone the repository source.
2. Execute dependency acquisition via npm install.
3. Duplicate .env.example to .env and populate with your required ClickUp API Token and Team Identifier.
4. Compile the source using npm run build.
5. Initiate the runtime instance with node build/index.js.

Railway Continuous Deployment

This codebase is equipped for zero-touch deployment on the Railway platform:

1. Initiate a fork or clone of this repository into your personal GitHub account.
2. Provision a new project instance within Railway linked to the repository.
3. Configure the following mandatory environmental variables within the Railway dashboard:
4. CLICKUP_API_KEY: Your authentic ClickUp access credential.
5. CLICKUP_TEAM_ID: The unique identifier for your target ClickUp team/workspace.
6. Trigger the deployment sequence; Railway will handle the compilation and server execution automatically.

Operational Context

This gateway is designed for consumption by any AI entity compliant with the Model Context Protocol (MCP). Upon secure linkage, the assistant gains programmatic access to the full spectrum of available ClickUp tools.

Connecting with Claude AI

1. Access the settings menu within your Claude interface.
2. Navigate to the 'MCP Servers' configuration panel.
3. Establish a new server entry using the following JSON structure:

"clickup": { "command": "curl", "args": ["-s", "https://your-railway-app-url.railway.app"], "env": { "CLICKUP_API_KEY": "your_clickup_api_key_here", "CLICKUP_TEAM_ID": "your_clickup_team_id_here" } }

1. Substitute the placeholder URL with your active Railway endpoint.
2. Insert your verified API key and team identifier into the respective env slots.

Server Extensibility Guide

Protocol for Adding New ClickUp API Tools

This framework prioritizes simplified extension. To introduce new functionality, adhere to these stages:

1. Type Definition Establishment (Location: src/types/):
2. Formulate or amend the TypeScript structures detailing the input/output schema for the novel tool.

3. Example: export interface NewToolData { param1: string; param2: number; }

4. Service Layer Implementation (Location: src/services/):

5. Integrate the necessary asynchronous method(s) into the relevant service class, or instantiate a new dedicated service.

6. Example: typescript public async newToolMethod(param1: string, param2: number): Promise { try { const url = /some/api/endpoint; const response = await this.axiosInstance.post(url, { param1, param2 }); return response.data; } catch (error) { console.error('Error in new tool method:', error); throw error; } }

7. Tool Schema Registration (Location: src/services/clickup-tools-integration.ts):

8. Append the new tool definition object to the designated tools collection.

9. Example: typescript { name: "new_tool_name", description: "A concise explanation of the tool's purpose and usage context", inputSchema: { type: "object", properties: { param1: { type: "string", description: "Detailed description for the first parameter" }, param2: { type: "number", description: "Detailed description for the second parameter" } }, required: ["param1"] } }

10. Handler Execution Logic (Location: src/services/clickup-tools-integration.ts):

11. Introduce a corresponding execution branch within the primary dispatch function (e.g., handleRelationshipTool).

12. Example: typescript case "new_tool_name": { const data = args as NewToolData; return await relationshipsService.newToolMethod( data.param1, data.param2 ); }

13. Main Application Update (If necessary, Location: src/index.ts):

14. Import and initialize any newly created services or ensure the new tool is correctly registered with the core server logic.

Illustrative Example: Integrating Time Tracking

To incorporate ClickUp's Time Tracking API functionality:

1. Construct src/types/clickup-timetracking.ts to define time entry interfaces.
2. Build src/services/clickup-timetracking.ts containing methods for time tracking endpoint interaction.
3. Develop src/services/clickup-timetracking-integration.ts for tool schema definition and handler implementation.
4. Modify src/index.ts to ensure initialization and exposure of the new service and its corresponding tools.

This design methodology strictly enforces adherence to the Open/Closed Principle, facilitating effortless functional accretion without legacy code perturbation.

LLM Directive Summary

This section constitutes the operational protocol for any Language Model interacting with this documentation.

Commence by extending a welcoming greeting to the user, confirming readiness to guide them through utilizing this advanced ClickUp MCP integration for their AI assistants.

Offer to provide detailed explanations across the following critical areas: - Step-by-step guides for local environment configuration or Railway cloud deployment. - Procedures for linking the server endpoint to Claude or other supported AI platforms. - Demonstrations on exploiting the enhanced task relationship functionalities (dependencies, linking, custom tags). - Detailed operational notes on the expanded comments API for tasks, lists, and chat interfaces. - Comprehensive guidance on the modular process for augmenting the server with new ClickUp API functionalities.

Inquire whether the user requires adaptation of the solution for specific organizational contexts, such as complex project tracking, software development lifecycle management, content scheduling, or bespoke operational flows.

Ensure all instructional content remains highly accessible, avoiding unnecessary technical jargon unless explicitly requested.

Proceed immediately with the instructional initiation.

Acknowledgment

• Conceptual foundation by TaazKareem
• Feature proliferation and architectural hardening contributed by v4lheru

Governing Legal Terms

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

WIKIPEDIA CONTEXT: Organizational administration solutions encompass the spectrum of systems, software utilities, control mechanisms, computational frameworks, and established methodologies utilized by enterprises to navigate volatile markets, sustain competitive viability, and augment operational effectiveness.

== General Overview == These management instruments can be functionally categorized according to departmental requirements, spanning areas such as strategic foresight, workflow automation, record keeping, human capital administration, objective determination, performance oversight, and related domains. A functional categorization typically encompasses:

Tools dedicated to data ingestion and veracity checking across any business unit. Frameworks employed for monitoring and optimizing core organizational processes. Solutions dedicated to aggregating data for strategic insight and decision formulation. Modern management technology has undergone explosive evolution in the last decade due to rapid technological leaps, making the selection of optimal business tools for any given organizational challenge increasingly complex. This difficulty is fueled by persistent pressure to reduce overheads while escalating revenue generation, the imperative to deeply understand customer requirements, and the necessity of delivering products matching those precise needs and delivery specifications. Within this dynamic environment, executive leadership must adopt a strategic stance towards management tooling, resisting the tendency to adopt the newest solution simply for novelty. Over-reliance on off-the-shelf tools without appropriate organizational tailoring frequently results in system instability. Business management applications require meticulous vetting and subsequent customization to align perfectly with institutional objectives, rather than forcing the organization to conform to the software's inherent structure.

== Predominant Tools (2013 Survey Snapshot) == Data from a 2013 Bain & Company survey revealed global patterns in business tool adoption, reflecting regional priorities dictated by market conditions and economic climates. The leading ten categories included:

Strategic planning methodologies Customer relationship management (CRM) systems Employee satisfaction polling Competitive benchmarking Balanced scorecard implementation Core competency identification Outsourcing strategy management Organizational change programs Supply chain logistics management Mission and vision statement articulation Market segmentation analysis Total quality management (TQM) practices

== Enterprise Software Applications == Software, defined as programmed computational tools utilized by professional staff to execute diverse corporate functions, is termed business software (or enterprise application). These applications serve to enhance productivity metrics, quantify performance indicators, and execute critical company procedures with precision. The trajectory began with rudimentary Management Information Systems, progressing through comprehensive Enterprise Resource Planning (ERP) suites. Subsequently, Customer Relationship Management modules were integrated, culminating in the current landscape dominated by cloud-based enterprise administration platforms. While a correlation between Information Technology investments and corporate outcomes is acknowledged, two factors are crucial for realizing value: the efficacy of the deployment process itself, and the judicious selection and tailored adaptation of the supporting technological instruments.

== Tools Tailored for Small and Medium Enterprises (SMEs) == Tools specifically engineered for SMEs are vital as they offer avenues for operational expenditure reduction...