@taazkareem/clickup-mcp-server 0.2.1 → 0.2.2

package/README.md

@@ -2,38 +2,20 @@
 
 A Model Context Protocol (MCP) server for integrating ClickUp tasks with AI applications. This server allows AI agents to interact with ClickUp tasks, spaces, lists, and folders through a standardized protocol.
 
-## Quick Start (Recommended)
+## Quick Start
 
-1. Install the server:
-```bash
-npm install -g @taazkareem/clickup-mcp-server
-```
+Directions for use with Cursor Composer Agent:
 
-2. Get your credentials:
+1. Get your credentials:
    - ClickUp API key from [ClickUp Settings](https://app.clickup.com/settings/apps)
    - Team ID from your ClickUp workspace URL
-
-3. Start the server:
-```bash
-clickup-mcp-server --env CLICKUP_API_KEY=your_api_key_here --env TEAM_ID=your_team_id_here
-```
-
-> **Security Note**: Your API key will be stored securely and not exposed to AI models.
-
-## Using with Cursor AI Composer
-
-1. Go to Features in settings
-2. Add under MCP Servers:
-```bash
-clickup-mcp-server --env CLICKUP_API_KEY=your_api_key_here --env TEAM_ID=your_team_id_here
-```
-3. Replace the credentials and click Save
-
-## Alternative Installation
-Run directly without installing:
+2. Go to Features in settings
+3. Add under MCP Servers:
 ```bash
-npx @taazkareem/clickup-mcp-server --env CLICKUP_API_KEY=your_api_key_here --env TEAM_ID=your_team_id_here
+npx -y @taazkareem/clickup-mcp-server --env CLICKUP_API_KEY=your_api_key_here --env CLICKUP_TEAM_ID=your_team_id_here
 ```
+4. Replace the credentials and click Save
+5. Use Natural Language to interact with your ClickUp Workspace!
 
 ## Features
 
@@ -65,224 +47,44 @@ npx @taazkareem/clickup-mcp-server --env CLICKUP_API_KEY=your_api_key_here --env
 
 ## Available Tools
 
-1. **get_workspace_hierarchy**
-   - Gets complete hierarchy of spaces, folders, and lists
-   - No parameters required
-   - Returns tree structure showing:
-     ```
-     Workspace (root)
-     ├── Space A
-     │   ├── List 1
-     │   └── Folder 1
-     │       ├── List 2
-     │       └── List 3
-     └── Space B
-         └── List 4
-     ```
-
-2. **get_tasks**
-   - Gets tasks from a ClickUp list with optional filters
-   - List Identification (required):
-     ```
-     listId: "123"      # List ID from ClickUp
-     -- OR --
-     listName: "My List" # List name (case insensitive)
-     ```
-   - Optional Filters:
-     ```
-     archived: true/false        # Include archived tasks
-     page: number               # Page number for pagination
-     order_by: string          # Field to sort by
-     reverse: true/false       # Reverse sort order
-     subtasks: true/false      # Include subtasks
-     statuses: ["status1",..] # Filter by status
-     include_closed: true/false # Include closed tasks
-     assignees: ["user1",..]   # Filter by assignee
-     due_date_gt: timestamp    # Due after date
-     due_date_lt: timestamp    # Due before date
-     custom_fields: {...}      # Filter by custom fields
-     ```
-
-3. **get_task**
-   - Gets detailed information about a specific task
-   - Task Identification (required):
-     ```
-     taskId: "123"       # Task ID from ClickUp
-     -- OR --
-     taskName: "My Task" # Task name (case insensitive)
-     ```
-   - Optional:
-     ```
-     listName: "My List" # Narrow search to specific list
-     ```
-   - Returns full task details including attachments and custom fields
-
-4. **create_task**
-   - Creates a new task in ClickUp
-   - List Identification (required):
-     ```
-     listId: "123"      # List ID from ClickUp
-     -- OR --
-     listName: "My List" # List name (case insensitive)
-     ```
-   - Task Details:
-     ```
-     # Required
-     taskName: "New Task"  # Name of the task to create
-
-     # Optional
-     description: "..."    # Task description (markdown supported)
-     status: "In Progress" # Task status
-     priority: 1-4        # Priority level (1=Urgent, 4=Low)
-     dueDate: timestamp   # Due date
-     ```
-
-5. **create_bulk_tasks**
-   - Creates multiple tasks in a list
-   - List Identification (required):
-     ```
-     listId: "123"      # List ID from ClickUp
-     -- OR --
-     listName: "My List" # List name (case insensitive)
-     ```
-   - Tasks Array (required):
-     ```
-     tasks: [
-       {
-         taskName: "Task 1",    # Required
-         description: "...",    # Optional
-         status: "In Progress", # Optional
-         priority: 1-4,        # Optional
-         dueDate: timestamp    # Optional
-       },
-       // ... more tasks
-     ]
-     ```
-   - Handles rate limiting automatically
-
-6. **update_task**
-   - Updates an existing task
-   - Task Identification (required):
-     ```
-     taskId: "123"       # Task ID from ClickUp
-     -- OR --
-     taskName: "My Task" # Task name (case insensitive)
-     ```
-   - Optional Updates:
-     ```
-     listName: "My List"     # Narrow search to specific list
-     newName: "Updated Task" # New task name
-     description: "..."      # New description
-     status: "Done"         # New status
-     priority: 1-4          # New priority
-     dueDate: timestamp     # New due date
-     ```
-
-7. **delete_task**
-   - Permanently deletes a task
-   - Task Identification (required):
-     ```
-     taskId: "123"       # Task ID from ClickUp
-     -- OR --
-     taskName: "My Task" # Task name (case insensitive)
-     ```
-   - Optional:
-     ```
-     listName: "My List" # Narrow search to specific list
-     ```
-
-8. **move_task**
-   - Moves a task to a different list
-   - Source Task (required):
-     ```
-     taskId: "123"       # Task ID from ClickUp
-     -- OR --
-     taskName: "My Task" # Task name (case insensitive)
-     ```
-   - Destination List (required):
-     ```
-     destinationListId: "456"      # Target list ID
-     -- OR --
-     destinationListName: "My List" # Target list name
-     ```
-   - Optional:
-     ```
-     sourceListName: "Old List" # Narrow task search to specific list
-     ```
-
-9. **duplicate_task**
-   - Creates a copy of a task in specified list
-   - Source Task (required):
-     ```
-     taskId: "123"       # Task ID from ClickUp
-     -- OR --
-     taskName: "My Task" # Task name (case insensitive)
-     ```
-   - Destination List (required):
-     ```
-     destinationListId: "456"      # Target list ID
-     -- OR --
-     destinationListName: "My List" # Target list name
-     ```
-   - Optional:
-     ```
-     sourceListName: "Current List" # Narrow task search to specific list
-     ```
-
-10. **create_list**
-    - Creates a new list in a space
-    - Space Identification (required):
-      ```
-      spaceId: "123"       # Space ID from ClickUp
-      -- OR --
-      spaceName: "My Space" # Space name (case insensitive)
-      ```
-    - List Details:
-      ```
-      # Required
-      listName: "New List" # Name for the new list
-
-      # Optional
-      content: "..."      # List description
-      dueDate: timestamp  # List due date
-      priority: 1-4       # List priority
-      assignee: "user_id" # Assign to user
-      ```
-
-11. **create_folder**
-    - Creates a new folder in a space
-    - Space Identification (required):
-      ```
-      spaceId: "123"       # Space ID from ClickUp
-      -- OR --
-      spaceName: "My Space" # Space name (case insensitive)
-      ```
-    - Folder Details:
-      ```
-      # Required
-      folderName: "New Folder" # Name for the new folder
-
-      # Optional
-      overrideStatuses: true/false # Override space statuses
-      ```
-
-12. **create_list_in_folder**
-    - Creates a new list within a folder
-    - Folder Identification (required):
-      ```
-      folderId: "123"        # Folder ID from ClickUp
-      -- OR --
-      folderName: "My Folder" # Folder name (case insensitive)
-      ```
-    - List Details:
-      ```
-      # Required
-      listName: "New List" # Name for the new list
-
-      # Optional
-      content: "..."      # List description
-      status: "Active"    # Initial list status
-      ```
+### Workspace Tools
+**get_workspace_hierarchy**
+Returns complete workspace structure (spaces, folders, lists). No parameters required.
+
+### Task Tools
+**get_tasks** `(listId|listName)`
+Get tasks from list with optional filters (archived, page, order_by, reverse, subtasks, statuses, include_closed, assignees, due_date_gt/lt, custom_fields).
+
+**get_task** `(taskId|taskName, ?listName)`
+Get detailed task info including attachments and custom fields.
+
+**create_task** `(listId|listName, taskName)`
+Create task with optional description (markdown), status, priority (1-4), dueDate.
+
+**create_bulk_tasks** `(listId|listName, tasks[])`
+Bulk create tasks with automatic rate limiting. Each task: name (required), description, status, priority, dueDate (optional).
+
+**update_task** `(taskId|taskName, ?listName)`
+Update task name, description, status, priority (1-4), dueDate.
+
+**delete_task** `(taskId|taskName, ?listName)`
+Permanently delete a task.
+
+**move_task** `(taskId|taskName, destinationListId|destinationListName, ?sourceListName)`
+Move task to different list, preserving task data.
+
+**duplicate_task** `(taskId|taskName, destinationListId|destinationListName, ?sourceListName)`
+Create copy of task in specified list.
+
+### List & Folder Tools
+**create_list** `(spaceId|spaceName, listName)`
+Create list with optional content, dueDate, priority (1-4), assignee.
+
+**create_folder** `(spaceId|spaceName, folderName, ?overrideStatuses)`
+Create folder in space.
+
+**create_list_in_folder** `(folderId|folderName, listName)`
+Create list in folder with optional content and status.
 
 ## Available Prompts
 

package/build/config.js

@@ -1,4 +1,3 @@
-// Parse command line arguments for --env flags
 const args = process.argv.slice(2);
 const envArgs = {};
 for (let i = 0; i < args.length; i++) {
@@ -6,16 +5,15 @@ for (let i = 0; i < args.length; i++) {
         const [key, value] = args[i + 1].split('=');
         if (key === 'CLICKUP_API_KEY')
             envArgs.clickupApiKey = value;
-        if (key === 'TEAM_ID')
-            envArgs.teamId = value;
-        i++; // Skip the next argument since we used it
+        if (key === 'CLICKUP_TEAM_ID')
+            envArgs.clickupTeamId = value;
+        i++;
     }
 }
 const configuration = {
-    clickupApiKey: envArgs.clickupApiKey || '',
-    teamId: envArgs.teamId || '',
+    clickupApiKey: envArgs.clickupApiKey || process.env.CLICKUP_API_KEY || '',
+    clickupTeamId: envArgs.clickupTeamId || process.env.CLICKUP_TEAM_ID || '',
 };
-// Check for missing environment variables
 const missingEnvVars = Object.entries(configuration)
     .filter(([_, value]) => !value)
     .map(([key]) => key);

package/build/index.js

@@ -25,7 +25,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema
 import { ClickUpService } from "./services/clickup.js";
 import config from "./config.js";
 // Initialize ClickUp service
-const clickup = ClickUpService.initialize(config.clickupApiKey, config.teamId);
+const clickup = ClickUpService.initialize(config.clickupApiKey, config.clickupTeamId);
 /**
  * Create an MCP server with capabilities for tools and prompts.
  * Resources have been removed as they are being replaced with direct tool calls.
@@ -852,7 +852,7 @@ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
     try {
         switch (request.params.name) {
             case "summarize_tasks": {
-                const spaces = await clickup.getSpaces(config.teamId);
+                const spaces = await clickup.getSpaces(config.clickupTeamId);
                 const tasks = [];
                 // Gather all tasks
                 for (const space of spaces) {
@@ -893,7 +893,7 @@ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
                 };
             }
             case "analyze_priorities": {
-                const spaces = await clickup.getSpaces(config.teamId);
+                const spaces = await clickup.getSpaces(config.clickupTeamId);
                 const tasks = [];
                 for (const space of spaces) {
                     const lists = await clickup.getLists(space.id);

package/build/services/clickup.js

@@ -6,10 +6,10 @@ import axios from 'axios';
 export class ClickUpService {
     client;
     static instance;
-    teamId;
+    clickupTeamId;
     rateLimitRemaining = 100; // Default to lowest tier limit
     rateLimitReset = 0;
-    constructor(apiKey, teamId) {
+    constructor(apiKey, clickupTeamId) {
         this.client = axios.create({
             baseURL: 'https://api.clickup.com/api/v2',
             headers: {
@@ -35,7 +35,7 @@ export class ClickUpService {
             }
             throw error;
         });
-        this.teamId = teamId;
+        this.clickupTeamId = clickupTeamId;
     }
     /**
      * Checks if we're close to hitting rate limits and waits if necessary.
@@ -73,13 +73,13 @@ export class ClickUpService {
     /**
      * Initializes the ClickUpService singleton instance.
      * @param apiKey - The ClickUp API key for authentication
-     * @param teamId - The team/workspace ID to operate on
+     * @param clickupTeamId - The team/workspace ID to operate on
      * @returns The singleton instance of ClickUpService
      * @throws Error if initialization fails
      */
-    static initialize(apiKey, teamId) {
+    static initialize(apiKey, clickupTeamId) {
         if (!ClickUpService.instance) {
-            ClickUpService.instance = new ClickUpService(apiKey, teamId);
+            ClickUpService.instance = new ClickUpService(apiKey, clickupTeamId);
         }
         return ClickUpService.instance;
     }
@@ -244,13 +244,13 @@ export class ClickUpService {
     }
     /**
      * Gets all lists in the workspace.
-     * @param teamId - ID of the team/workspace
+     * @param clickupTeamId - ID of the team/workspace
      * @returns Promise resolving to array of ClickUpList objects
      * @throws Error if the API request fails
      */
-    async getAllLists(teamId) {
+    async getAllLists(clickupTeamId) {
         return this.makeRequest(async () => {
-            const response = await this.client.get(`/team/${teamId}/list`);
+            const response = await this.client.get(`/team/${clickupTeamId}/list`);
             return response.data.lists;
         });
     }
@@ -267,9 +267,9 @@ export class ClickUpService {
         });
     }
     // Spaces
-    async getSpaces(teamId) {
+    async getSpaces(clickupTeamId) {
         return this.makeRequest(async () => {
-            const response = await this.client.get(`/team/${teamId}/space`);
+            const response = await this.client.get(`/team/${clickupTeamId}/space`);
             return response.data.spaces;
         });
     }
@@ -279,8 +279,8 @@ export class ClickUpService {
             return response.data;
         });
     }
-    async findSpaceByName(teamId, spaceName) {
-        const spaces = await this.getSpaces(teamId);
+    async findSpaceByName(clickupTeamId, spaceName) {
+        const spaces = await this.getSpaces(clickupTeamId);
         return spaces.find(space => space.name.toLowerCase() === spaceName.toLowerCase()) || null;
     }
     /**
@@ -448,7 +448,7 @@ export class ClickUpService {
     }
     async findListByNameGlobally(listName) {
         // First try the direct lists
-        const lists = await this.getAllLists(this.teamId);
+        const lists = await this.getAllLists(this.clickupTeamId);
         const directList = lists.find(list => list.name.toLowerCase() === listName.toLowerCase());
         if (directList)
             return directList;
@@ -477,9 +477,9 @@ export class ClickUpService {
      * @throws Error if API requests fail
      */
     async getWorkspaceHierarchy() {
-        const spaces = await this.getSpaces(this.teamId);
+        const spaces = await this.getSpaces(this.clickupTeamId);
         const root = {
-            id: this.teamId,
+            id: this.clickupTeamId,
             name: 'Workspace',
             type: 'workspace',
             children: []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taazkareem/clickup-mcp-server",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "ClickUp MCP Server - Integrate ClickUp tasks with AI through Model Context Protocol",
   "type": "module",
   "main": "build/index.js",