@taazkareem/clickup-mcp-server 0.1.7 → 0.3.0

package/README.md

@@ -1,15 +1,41 @@
 # ClickUp MCP Server
 
-A Model Context Protocol (MCP) server for integrating ClickUp tasks with AI applications. This server allows AI agents to interact with ClickUp tasks, spaces, and lists through a standardized protocol.
+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.
 
 ## Features
 
-- 🔄 List and read ClickUp tasks as resources
-- ✨ Create and update tasks through tools
-- 📊 Get spaces and lists with their IDs
-- 📝 Generate task descriptions with AI
-- 📋 Summarize tasks and analyze priorities
-- 🔒 Secure API key management
+- 🔄 **Resource Management**
+  - List and read ClickUp tasks as resources
+  - View task details, status, and assignments
+  - Access task history and relationships
+
+- 📂 **Workspace Organization**
+  - Create and manage spaces
+  - Create, update, and delete folders
+  - Create and manage lists (in spaces or folders)
+  - Flexible identification using IDs or names
+
+- ✨ **Task Operations**
+  - Create and update tasks
+  - Move tasks between lists
+  - Duplicate tasks
+  - Set priorities and due dates
+  - Assign team members
+
+- 📊 **Information Retrieval**
+  - Get spaces and lists with their IDs
+  - List available statuses
+  - Find items by name (case-insensitive)
+  - View task relationships
+
+- 📝 **AI Integration**
+  - Generate task descriptions with AI
+  - Summarize tasks and analyze priorities
+  - Get AI-powered task recommendations
+
+- 🔒 **Security**
+  - Secure API key management
+  - Environment-based configuration
 
 ## Installation
 
@@ -32,17 +58,32 @@ CLICKUP_API_KEY=your_api_key_here
 TEAM_ID=your_team_id_here
 ```
 
-## Usage
+## Using with Cursor AI Composer
+
+To add this server to Cursor AI Composer, follow these steps:
+
+1. Go to the Features section in the settings.
+2. Add the following command under MCP Servers:
 
-### Starting the Server
 ```bash
-clickup-mcp-server
+npx -y @taazkareem/clickup-mcp-server \
+  --env CLICKUP_API_KEY=your_api_key_here \
+  --env TEAM_ID=your_team_id_here
 ```
+3. Replace `your_api_key_here` and `your_team_id_here` with your actual ClickUp credentials.
+4. Click on 'Save' to add the server.
+
+You can get these values from:
+- `CLICKUP_API_KEY`: Get from [ClickUp Settings > Apps](https://app.clickup.com/settings/apps)
+- `TEAM_ID`: Your ClickUp Team ID (found in the URL when viewing your workspace or via API)
+
+> **Security Note**: Your API key will be stored securely and will not be exposed to AI models.
 
 ### Available Tools
 
 1. **list_spaces**
    - Lists all spaces and their lists with IDs
+   - Shows available statuses for each list
    - No parameters required
 
 2. **create_task**
@@ -55,51 +96,122 @@ clickup-mcp-server
      - `status`: Task status
      - `priority`: Priority level (1-4)
      - `dueDate`: Due date (ISO string)
+     - `assignees`: Array of user IDs
+
+3. **create_bulk_tasks**
+   - Creates multiple tasks simultaneously in a list
+   - Required parameters:
+     - `listId`: ID of the list to create the tasks in
+     - `tasks`: Array of task objects, each containing:
+       - `name`: Name of the task (required)
+       - `description`: Task description (optional)
+       - `status`: Task status (optional)
+       - `priority`: Priority level 1-4 (optional)
+       - `dueDate`: Due date ISO string (optional)
+       - `assignees`: Array of user IDs (optional)
+
+4. **create_list**
+   - Creates a new list in a space
+   - Required parameters:
+     - `name`: Name of the list
+   - Optional parameters:
+     - `spaceId`: ID of the space (optional if spaceName provided)
+     - `spaceName`: Name of the space (optional if spaceId provided)
+     - `content`: List description
+     - `status`: List status
+     - `priority`: Priority level (1-4)
+     - `dueDate`: Due date (ISO string)
+
+5. **create_folder**
+   - Creates a new folder in a space
+   - Required parameters:
+     - `name`: Name of the folder
+   - Optional parameters:
+     - `spaceId`: ID of the space (optional if spaceName provided)
+     - `spaceName`: Name of the space (optional if spaceId provided)
+     - `override_statuses`: Whether to override space statuses
+
+6. **create_list_in_folder**
+   - Creates a new list within a folder
+   - Required parameters:
+     - `name`: Name of the list
+   - Optional parameters:
+     - `folderId`: ID of the folder (optional if using folderName)
+     - `folderName`: Name of the folder
+     - `spaceId`: ID of the space (required if using folderName)
+     - `spaceName`: Name of the space (alternative to spaceId)
+     - `content`: List description
+     - `status`: List status
+
+7. **move_task**
+   - Moves a task to a different list
+   - Required parameters:
+     - `taskId`: ID of the task to move
+     - `listId`: ID of the destination list
+
+8. **duplicate_task**
+   - Creates a copy of a task in a specified list
+   - Required parameters:
+     - `taskId`: ID of the task to duplicate
+     - `listId`: ID of the destination list
 
-3. **update_task**
+9. **update_task**
    - Updates an existing task
    - Required parameters:
      - `taskId`: ID of the task to update
    - Optional parameters:
-     - Same as create_task
+     - `name`: New task name
+     - `description`: New description
+     - `status`: New status
+     - `priority`: New priority level (1-4)
+     - `dueDate`: New due date (ISO string)
 
 ### Available Prompts
 
 1. **summarize_tasks**
-   - Provides a summary of all tasks
-   - Groups by status and highlights priorities
+   - Provides a comprehensive summary of tasks
+   - Groups tasks by status
+   - Highlights priorities and deadlines
+   - Suggests task relationships
 
 2. **analyze_priorities**
-   - Analyzes task priorities
-   - Suggests optimizations and sequencing
+   - Analyzes task priority distribution
+   - Identifies misaligned priorities
+   - Suggests priority adjustments
+   - Recommends task sequencing
 
 3. **generate_description**
    - Helps generate detailed task descriptions
-   - Includes objectives, criteria, and dependencies
+   - Includes:
+     - Clear objectives
+     - Success criteria
+     - Required resources
+     - Dependencies
+     - Potential risks
 
-## Using with Cursor AI Composer
+## Name Resolution
 
-To add this server to Cursor AI Composer:
+Most tools support finding items by either ID or name:
+- Spaces can be referenced by `spaceId` or `spaceName`
+- Folders can be referenced by `folderId` or `folderName` (with space information)
+- Lists can be referenced by `listId` or found within spaces/folders
 
-```bash
-npx -y @taazkareem/clickup-mcp-server \
-  --env CLICKUP_API_KEY=your_api_key_here \
-  --env TEAM_ID=your_team_id_here
-```
+Name matching is case-insensitive for convenience.
 
-You can get these values from:
-- `CLICKUP_API_KEY`: Get from [ClickUp Settings > Apps](https://app.clickup.com/settings/apps)
-- `TEAM_ID`: Your ClickUp Team ID (found in the URL when viewing your workspace or via API)
+## Error Handling
 
-> ⚠️ **Important**: Make sure to replace `your_api_key_here` and `your_team_id_here` with your actual ClickUp credentials.
-
-> **Security Note**: Your API key will be stored securely and will not be exposed to AI models.
+The server provides clear error messages for common scenarios:
+- Missing required parameters
+- Invalid IDs or names
+- Items not found
+- Permission issues
+- API errors
 
 ## Development
 
 1. Clone the repository:
 ```bash
-git clone https://github.com/yourusername/clickup-mcp-server.git
+git clone https://github.com/taazkareem/clickup-mcp-server.git
 cd clickup-mcp-server
 ```
 
@@ -119,4 +231,4 @@ Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md)
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. 

package/build/index.js

@@ -143,6 +143,199 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     required: ["listId", "name"]
                 }
             },
+            {
+                name: "create_bulk_tasks",
+                description: "Create multiple tasks in a ClickUp list",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        listId: {
+                            type: "string",
+                            description: "ID of the list to create the tasks in"
+                        },
+                        tasks: {
+                            type: "array",
+                            description: "Array of tasks to create",
+                            items: {
+                                type: "object",
+                                properties: {
+                                    name: {
+                                        type: "string",
+                                        description: "Name of the task"
+                                    },
+                                    description: {
+                                        type: "string",
+                                        description: "Description of the task"
+                                    },
+                                    status: {
+                                        type: "string",
+                                        description: "Status of the task"
+                                    },
+                                    priority: {
+                                        type: "number",
+                                        description: "Priority level (1-4)"
+                                    },
+                                    dueDate: {
+                                        type: "string",
+                                        description: "Due date of the task (ISO string)"
+                                    },
+                                    assignees: {
+                                        type: "array",
+                                        items: {
+                                            type: "number"
+                                        },
+                                        description: "Array of user IDs to assign to the task"
+                                    }
+                                },
+                                required: ["name"]
+                            }
+                        }
+                    },
+                    required: ["listId", "tasks"]
+                }
+            },
+            {
+                name: "create_list",
+                description: "Create a new list in a ClickUp space",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        spaceId: {
+                            type: "string",
+                            description: "ID of the space to create the list in (optional if spaceName is provided)"
+                        },
+                        spaceName: {
+                            type: "string",
+                            description: "Name of the space to create the list in (optional if spaceId is provided)"
+                        },
+                        name: {
+                            type: "string",
+                            description: "Name of the list"
+                        },
+                        content: {
+                            type: "string",
+                            description: "Description or content of the list"
+                        },
+                        dueDate: {
+                            type: "string",
+                            description: "Due date for the list (ISO string)"
+                        },
+                        priority: {
+                            type: "number",
+                            description: "Priority of the list (1-4)"
+                        },
+                        assignee: {
+                            type: "number",
+                            description: "User ID to assign the list to"
+                        },
+                        status: {
+                            type: "string",
+                            description: "Status of the list"
+                        }
+                    },
+                    required: ["name"]
+                }
+            },
+            {
+                name: "create_folder",
+                description: "Create a new folder in a ClickUp space",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        spaceId: {
+                            type: "string",
+                            description: "ID of the space to create the folder in (optional if spaceName is provided)"
+                        },
+                        spaceName: {
+                            type: "string",
+                            description: "Name of the space to create the folder in (optional if spaceId is provided)"
+                        },
+                        name: {
+                            type: "string",
+                            description: "Name of the folder"
+                        },
+                        override_statuses: {
+                            type: "boolean",
+                            description: "Whether to override space statuses"
+                        }
+                    },
+                    required: ["name"]
+                }
+            },
+            {
+                name: "create_list_in_folder",
+                description: "Create a new list in a ClickUp folder",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        folderId: {
+                            type: "string",
+                            description: "ID of the folder to create the list in (optional if folderName and spaceId/spaceName are provided)"
+                        },
+                        folderName: {
+                            type: "string",
+                            description: "Name of the folder to create the list in"
+                        },
+                        spaceId: {
+                            type: "string",
+                            description: "ID of the space containing the folder (required if using folderName)"
+                        },
+                        spaceName: {
+                            type: "string",
+                            description: "Name of the space containing the folder (alternative to spaceId)"
+                        },
+                        name: {
+                            type: "string",
+                            description: "Name of the list"
+                        },
+                        content: {
+                            type: "string",
+                            description: "Description or content of the list"
+                        },
+                        status: {
+                            type: "string",
+                            description: "Status of the list"
+                        }
+                    },
+                    required: ["name"]
+                }
+            },
+            {
+                name: "move_task",
+                description: "Move a task to a different list",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        taskId: {
+                            type: "string",
+                            description: "ID of the task to move"
+                        },
+                        listId: {
+                            type: "string",
+                            description: "ID of the destination list"
+                        }
+                    },
+                    required: ["taskId", "listId"]
+                }
+            },
+            {
+                name: "duplicate_task",
+                description: "Duplicate a task to a list",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        taskId: {
+                            type: "string",
+                            description: "ID of the task to duplicate"
+                        },
+                        listId: {
+                            type: "string",
+                            description: "ID of the list to create the duplicate in"
+                        }
+                    },
+                    required: ["taskId", "listId"]
+                }
+            },
             {
                 name: "update_task",
                 description: "Update an existing task in ClickUp",
@@ -232,6 +425,132 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         }]
                 };
             }
+            case "create_bulk_tasks": {
+                const args = request.params.arguments;
+                if (!args.listId || !args.tasks || !args.tasks.length) {
+                    throw new Error("listId and at least one task are required");
+                }
+                const { listId, tasks } = args;
+                const createdTasks = await clickup.createBulkTasks(listId, { tasks });
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Created ${createdTasks.length} tasks:\n${createdTasks.map(task => `- ${task.id}: ${task.name}`).join('\n')}`
+                        }]
+                };
+            }
+            case "create_list": {
+                const args = request.params.arguments;
+                if (!args.name) {
+                    throw new Error("name is required");
+                }
+                let spaceId = args.spaceId;
+                if (!spaceId && args.spaceName) {
+                    const space = await clickup.findSpaceByName(config.teamId, args.spaceName);
+                    if (!space) {
+                        throw new Error(`Space with name "${args.spaceName}" not found`);
+                    }
+                    spaceId = space.id;
+                }
+                if (!spaceId) {
+                    throw new Error("Either spaceId or spaceName must be provided");
+                }
+                const { spaceId: _, spaceName: __, ...listData } = args;
+                const list = await clickup.createList(spaceId, listData);
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Created list ${list.id}: ${list.name}`
+                        }]
+                };
+            }
+            case "create_folder": {
+                const args = request.params.arguments;
+                if (!args.name) {
+                    throw new Error("name is required");
+                }
+                let spaceId = args.spaceId;
+                if (!spaceId && args.spaceName) {
+                    const space = await clickup.findSpaceByName(config.teamId, args.spaceName);
+                    if (!space) {
+                        throw new Error(`Space with name "${args.spaceName}" not found`);
+                    }
+                    spaceId = space.id;
+                }
+                if (!spaceId) {
+                    throw new Error("Either spaceId or spaceName must be provided");
+                }
+                const { spaceId: _, spaceName: __, ...folderData } = args;
+                const folder = await clickup.createFolder(spaceId, folderData);
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Created folder ${folder.id}: ${folder.name}`
+                        }]
+                };
+            }
+            case "create_list_in_folder": {
+                const args = request.params.arguments;
+                if (!args.name) {
+                    throw new Error("name is required");
+                }
+                let folderId = args.folderId;
+                if (!folderId && args.folderName) {
+                    let spaceId = args.spaceId;
+                    if (!spaceId && args.spaceName) {
+                        const space = await clickup.findSpaceByName(config.teamId, args.spaceName);
+                        if (!space) {
+                            throw new Error(`Space with name "${args.spaceName}" not found`);
+                        }
+                        spaceId = space.id;
+                    }
+                    if (!spaceId) {
+                        throw new Error("Either spaceId or spaceName must be provided when using folderName");
+                    }
+                    const folder = await clickup.findFolderByName(spaceId, args.folderName);
+                    if (!folder) {
+                        throw new Error(`Folder with name "${args.folderName}" not found`);
+                    }
+                    folderId = folder.id;
+                }
+                if (!folderId) {
+                    throw new Error("Either folderId or folderName (with space information) must be provided");
+                }
+                const { folderId: _, folderName: __, spaceId: ___, spaceName: ____, ...listData } = args;
+                const list = await clickup.createListInFolder(folderId, listData);
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Created list ${list.id}: ${list.name} in folder`
+                        }]
+                };
+            }
+            case "move_task": {
+                const args = request.params.arguments;
+                if (!args.taskId || !args.listId) {
+                    throw new Error("taskId and listId are required");
+                }
+                const task = await clickup.moveTask(args.taskId, args.listId);
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Moved task ${task.id} to list ${args.listId}`
+                        }]
+                };
+            }
+            case "duplicate_task": {
+                const args = request.params.arguments;
+                if (!args.taskId || !args.listId) {
+                    throw new Error("taskId and listId are required");
+                }
+                const task = await clickup.duplicateTask(args.taskId, args.listId);
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Duplicated task ${args.taskId} to new task ${task.id} in list ${args.listId}`
+                        }]
+                };
+            }
             case "update_task": {
                 const args = request.params.arguments;
                 if (!args.taskId) {

package/build/services/clickup.js

@@ -38,6 +38,10 @@ export class ClickUpService {
         const response = await this.client.post(`/list/${listId}/task`, data);
         return response.data;
     }
+    async createBulkTasks(listId, data) {
+        const tasks = await Promise.all(data.tasks.map(taskData => this.createTask(listId, taskData)));
+        return tasks;
+    }
     async updateTask(taskId, data) {
         const response = await this.client.put(`/task/${taskId}`, data);
         return response.data;
@@ -67,4 +71,60 @@ export class ClickUpService {
         const response = await this.client.get(`/space/${spaceId}`);
         return response.data;
     }
+    async findSpaceByName(teamId, spaceName) {
+        const spaces = await this.getSpaces(teamId);
+        return spaces.find(space => space.name.toLowerCase() === spaceName.toLowerCase()) || null;
+    }
+    async createList(spaceId, data) {
+        const response = await this.client.post(`/space/${spaceId}/list`, data);
+        return response.data;
+    }
+    // Folders
+    async getFolders(spaceId) {
+        const response = await this.client.get(`/space/${spaceId}/folder`);
+        return response.data.folders;
+    }
+    async getFolder(folderId) {
+        const response = await this.client.get(`/folder/${folderId}`);
+        return response.data;
+    }
+    async createFolder(spaceId, data) {
+        const response = await this.client.post(`/space/${spaceId}/folder`, data);
+        return response.data;
+    }
+    async deleteFolder(folderId) {
+        await this.client.delete(`/folder/${folderId}`);
+    }
+    async createListInFolder(folderId, data) {
+        const response = await this.client.post(`/folder/${folderId}/list`, data);
+        return response.data;
+    }
+    async findFolderByName(spaceId, folderName) {
+        const folders = await this.getFolders(spaceId);
+        return folders.find(folder => folder.name.toLowerCase() === folderName.toLowerCase()) || null;
+    }
+    // Additional helper methods
+    async moveTask(taskId, listId) {
+        const response = await this.client.post(`/task/${taskId}`, {
+            list: listId
+        });
+        return response.data;
+    }
+    async duplicateTask(taskId, listId) {
+        const response = await this.client.post(`/task/${taskId}/duplicate`, {
+            list: listId
+        });
+        return response.data;
+    }
+    async deleteList(listId) {
+        await this.client.delete(`/list/${listId}`);
+    }
+    async updateList(listId, data) {
+        const response = await this.client.put(`/list/${listId}`, data);
+        return response.data;
+    }
+    async findListByName(spaceId, listName) {
+        const lists = await this.getLists(spaceId);
+        return lists.find(list => list.name.toLowerCase() === listName.toLowerCase()) || null;
+    }
 }

package/package.json

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