@griffinwork40/clickup-mcp-server 1.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 griffinwork40
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,173 @@
+# ClickUp MCP Server
+
+A Model Context Protocol (MCP) server that provides comprehensive integration with the ClickUp API. This server enables LLMs to manage tasks, projects, teams, and workflows programmatically.
+
+## Features
+
+### Organization & Hierarchy
+- List teams/workspaces
+- Browse spaces, folders, and lists
+- Get list details including statuses and custom fields
+
+### Task Management
+- Create, read, update, and delete tasks
+- Set task status, priority, assignees, and due dates
+- Manage task descriptions and details
+
+### Search & Collaboration
+- Search tasks across teams with filters
+- Add and retrieve comments on tasks
+
+### Advanced Features
+- Set custom field values
+- Track time on tasks
+- Get time entries
+
+## Installation
+
+```bash
+npm install
+npm run build
+```
+
+## Configuration
+
+Set your ClickUp API token as an environment variable:
+
+```bash
+export CLICKUP_API_TOKEN="pk_your_token_here"
+```
+
+To obtain an API token:
+1. Go to https://app.clickup.com/settings/apps
+2. Click "Generate" under "API Token"
+3. Copy the token (starts with `pk_`)
+
+## Usage
+
+### Run the server
+
+```bash
+npm start
+```
+
+### Development mode with auto-reload
+
+```bash
+npm run dev
+```
+
+### With Claude Desktop
+
+Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "clickup": {
+      "command": "node",
+      "args": ["/path/to/clickup-mcp-server/dist/index.js"],
+      "env": {
+        "CLICKUP_API_TOKEN": "pk_your_token_here"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### Organization Tools
+- `clickup_get_teams` - List all teams/workspaces
+- `clickup_get_spaces` - Get spaces in a team
+- `clickup_get_folders` - Get folders in a space
+- `clickup_get_lists` - Get lists in folder/space
+- `clickup_get_list_details` - Get list details with statuses and custom fields
+
+### Task Tools
+- `clickup_get_tasks` - Get tasks in a list (paginated)
+- `clickup_get_task` - Get detailed task information
+- `clickup_create_task` - Create a new task
+- `clickup_update_task` - Update task properties
+- `clickup_delete_task` - Delete a task
+
+### Search & Comments
+- `clickup_search_tasks` - Search for tasks across a team
+- `clickup_add_comment` - Add a comment to a task
+- `clickup_get_comments` - Get comments on a task
+
+### Advanced Tools
+- `clickup_set_custom_field` - Set custom field values
+- `clickup_start_time_entry` - Start time tracking
+- `clickup_stop_time_entry` - Stop time tracking
+- `clickup_get_time_entries` - Get time tracking entries
+
+## Response Formats
+
+All tools support two response formats:
+
+- **JSON** (`response_format: "json"`): Structured data for programmatic processing
+- **Markdown** (`response_format: "markdown"`): Human-readable formatted text (default)
+
+## Rate Limits
+
+ClickUp API rate limits:
+- 100 requests/minute (Business plan)
+- 1000 requests/minute (Business Plus and above)
+
+The server implements automatic error handling for rate limit responses.
+
+## Examples
+
+### Create a task
+
+```typescript
+{
+  "tool": "clickup_create_task",
+  "arguments": {
+    "list_id": "123456",
+    "name": "Implement new feature",
+    "description": "Add user authentication to the app",
+    "priority": 2,
+    "status": "to do",
+    "assignees": [123456]
+  }
+}
+```
+
+### Search for tasks
+
+```typescript
+{
+  "tool": "clickup_search_tasks",
+  "arguments": {
+    "team_id": "123456",
+    "query": "authentication",
+    "statuses": ["in progress", "to do"]
+  }
+}
+```
+
+## Development
+
+### Build
+
+```bash
+npm run build
+```
+
+### Clean
+
+```bash
+npm run clean
+```
+
+## License
+
+MIT
+
+## Links
+
+- [ClickUp API Documentation](https://clickup.com/api)
+- [MCP Protocol](https://modelcontextprotocol.io)
+- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)

package/dist/constants.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Constants and enumerations for ClickUp MCP server.
+ */
+export declare const API_BASE_URL = "https://api.clickup.com/api/v2";
+export declare const CHARACTER_LIMIT = 100000;
+export declare const DEFAULT_TIMEOUT = 30000;
+/**
+ * Response format options for tool outputs
+ */
+export declare enum ResponseFormat {
+    MARKDOWN = "markdown",
+    JSON = "json"
+}
+/**
+ * Response mode options for controlling data verbosity
+ */
+export declare enum ResponseMode {
+    FULL = "full",// Complete task details with all fields
+    COMPACT = "compact",// Essential fields only (id, name, status, assignees)
+    SUMMARY = "summary"
+}
+/**
+ * ClickUp task priority levels
+ */
+export declare enum Priority {
+    URGENT = 1,
+    HIGH = 2,
+    NORMAL = 3,
+    LOW = 4
+}
+/**
+ * Standard pagination defaults
+ */
+export declare const DEFAULT_LIMIT = 20;
+export declare const MAX_LIMIT = 100;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,YAAY,mCAAmC,CAAC;AAC7D,eAAO,MAAM,eAAe,SAAS,CAAC;AACtC,eAAO,MAAM,eAAe,QAAQ,CAAC;AAErC;;GAEG;AACH,oBAAY,cAAc;IACxB,QAAQ,aAAa;IACrB,IAAI,SAAS;CACd;AAED;;GAEG;AACH,oBAAY,YAAY;IACtB,IAAI,SAAS,CAAS,wCAAwC;IAC9D,OAAO,YAAY,CAAG,sDAAsD;IAC5E,OAAO,YAAY;CACpB;AAED;;GAEG;AACH,oBAAY,QAAQ;IAClB,MAAM,IAAI;IACV,IAAI,IAAI;IACR,MAAM,IAAI;IACV,GAAG,IAAI;CACR;AAED;;GAEG;AACH,eAAO,MAAM,aAAa,KAAK,CAAC;AAChC,eAAO,MAAM,SAAS,MAAM,CAAC"}

package/dist/constants.js

@@ -0,0 +1,39 @@
+/**
+ * Constants and enumerations for ClickUp MCP server.
+ */
+export const API_BASE_URL = "https://api.clickup.com/api/v2";
+export const CHARACTER_LIMIT = 100000;
+export const DEFAULT_TIMEOUT = 30000; // 30 seconds
+/**
+ * Response format options for tool outputs
+ */
+export var ResponseFormat;
+(function (ResponseFormat) {
+    ResponseFormat["MARKDOWN"] = "markdown";
+    ResponseFormat["JSON"] = "json";
+})(ResponseFormat || (ResponseFormat = {}));
+/**
+ * Response mode options for controlling data verbosity
+ */
+export var ResponseMode;
+(function (ResponseMode) {
+    ResponseMode["FULL"] = "full";
+    ResponseMode["COMPACT"] = "compact";
+    ResponseMode["SUMMARY"] = "summary"; // Statistical overview without individual task details
+})(ResponseMode || (ResponseMode = {}));
+/**
+ * ClickUp task priority levels
+ */
+export var Priority;
+(function (Priority) {
+    Priority[Priority["URGENT"] = 1] = "URGENT";
+    Priority[Priority["HIGH"] = 2] = "HIGH";
+    Priority[Priority["NORMAL"] = 3] = "NORMAL";
+    Priority[Priority["LOW"] = 4] = "LOW";
+})(Priority || (Priority = {}));
+/**
+ * Standard pagination defaults
+ */
+export const DEFAULT_LIMIT = 20;
+export const MAX_LIMIT = 100;
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,CAAC,MAAM,YAAY,GAAG,gCAAgC,CAAC;AAC7D,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC;AACtC,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,CAAC,CAAC,aAAa;AAEnD;;GAEG;AACH,MAAM,CAAN,IAAY,cAGX;AAHD,WAAY,cAAc;IACxB,uCAAqB,CAAA;IACrB,+BAAa,CAAA;AACf,CAAC,EAHW,cAAc,KAAd,cAAc,QAGzB;AAED;;GAEG;AACH,MAAM,CAAN,IAAY,YAIX;AAJD,WAAY,YAAY;IACtB,6BAAa,CAAA;IACb,mCAAmB,CAAA;IACnB,mCAAmB,CAAA,CAAG,uDAAuD;AAC/E,CAAC,EAJW,YAAY,KAAZ,YAAY,QAIvB;AAED;;GAEG;AACH,MAAM,CAAN,IAAY,QAKX;AALD,WAAY,QAAQ;IAClB,2CAAU,CAAA;IACV,uCAAQ,CAAA;IACR,2CAAU,CAAA;IACV,qCAAO,CAAA;AACT,CAAC,EALW,QAAQ,KAAR,QAAQ,QAKnB;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,EAAE,CAAC;AAChC,MAAM,CAAC,MAAM,SAAS,GAAG,GAAG,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * ClickUp MCP Server
+ *
+ * A Model Context Protocol server that provides comprehensive integration with the ClickUp API.
+ * Enables LLMs to manage tasks, projects, teams, and workflows programmatically.
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;GAKG"}