@taazkareem/clickup-mcp-server 0.1.7

package/README.md

@@ -0,0 +1,122 @@
+# 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.
+
+## 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
+
+## Installation
+
+### Using npx (Recommended)
+```bash
+npx @taazkareem/clickup-mcp-server
+```
+
+### Global Installation
+```bash
+npm install -g @taazkareem/clickup-mcp-server
+```
+
+## Configuration
+
+1. Get your ClickUp API key from [ClickUp Settings](https://app.clickup.com/settings/apps)
+2. Create a `.env` file:
+```env
+CLICKUP_API_KEY=your_api_key_here
+TEAM_ID=your_team_id_here
+```
+
+## Usage
+
+### Starting the Server
+```bash
+clickup-mcp-server
+```
+
+### Available Tools
+
+1. **list_spaces**
+   - Lists all spaces and their lists with IDs
+   - No parameters required
+
+2. **create_task**
+   - Creates a new task in ClickUp
+   - Required parameters:
+     - `listId`: ID of the list to create the task in
+     - `name`: Name of the task
+   - Optional parameters:
+     - `description`: Task description
+     - `status`: Task status
+     - `priority`: Priority level (1-4)
+     - `dueDate`: Due date (ISO string)
+
+3. **update_task**
+   - Updates an existing task
+   - Required parameters:
+     - `taskId`: ID of the task to update
+   - Optional parameters:
+     - Same as create_task
+
+### Available Prompts
+
+1. **summarize_tasks**
+   - Provides a summary of all tasks
+   - Groups by status and highlights priorities
+
+2. **analyze_priorities**
+   - Analyzes task priorities
+   - Suggests optimizations and sequencing
+
+3. **generate_description**
+   - Helps generate detailed task descriptions
+   - Includes objectives, criteria, and dependencies
+
+## Using with Cursor AI Composer
+
+To add this server to Cursor AI Composer:
+
+```bash
+npx -y @taazkareem/clickup-mcp-server \
+  --env CLICKUP_API_KEY=your_api_key_here \
+  --env TEAM_ID=your_team_id_here
+```
+
+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)
+
+> ⚠️ **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.
+
+## Development
+
+1. Clone the repository:
+```bash
+git clone https://github.com/yourusername/clickup-mcp-server.git
+cd clickup-mcp-server
+```
+
+2. Install dependencies:
+```bash
+npm install
+```
+
+3. Start in development mode:
+```bash
+npm run dev
+```
+
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/build/config.js

@@ -0,0 +1,28 @@
+import dotenv from 'dotenv';
+// Load environment variables from .env file
+dotenv.config();
+// Parse command line arguments for --env flags
+const args = process.argv.slice(2);
+const envArgs = {};
+for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--env' && i + 1 < args.length) {
+        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
+    }
+}
+const configuration = {
+    clickupApiKey: envArgs.clickupApiKey || process.env.CLICKUP_API_KEY || '',
+    teamId: envArgs.teamId || process.env.TEAM_ID || '',
+};
+// Check for missing environment variables
+const missingEnvVars = Object.entries(configuration)
+    .filter(([_, value]) => !value)
+    .map(([key]) => key);
+if (missingEnvVars.length > 0) {
+    throw new Error(`Missing required environment variables: ${missingEnvVars.join(', ')}`);
+}
+export default configuration;

package/build/index.js

@@ -0,0 +1,397 @@
+#!/usr/bin/env node
+/**
+ * This is a template MCP server that implements a simple ClickUp task management system.
+ * It demonstrates core MCP concepts like resources, tools, and prompts by allowing:
+ * - Listing ClickUp tasks as resources
+ * - Reading individual ClickUp tasks
+ * - Creating new ClickUp tasks via a tool
+ * - Updating existing ClickUp tasks via a tool
+ * - Summarizing all ClickUp tasks via a prompt
+ * - Analyzing task priorities via a prompt
+ * - Generating detailed descriptions for tasks via a prompt
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { ClickUpService } from "./services/clickup.js";
+import config from "./config.js";
+/**
+ * Simple in-memory storage for notes.
+ * In a real implementation, this would likely be backed by a database.
+ */
+const notes = {
+    "1": { title: "First Note", content: "This is note 1" },
+    "2": { title: "Second Note", content: "This is note 2" }
+};
+// Initialize ClickUp service
+const clickup = ClickUpService.initialize(config.clickupApiKey);
+/**
+ * Create an MCP server with capabilities for resources (to list/read ClickUp tasks),
+ * tools (to create/update ClickUp tasks), and prompts (to summarize/analyze ClickUp tasks).
+ */
+const server = new Server({
+    name: "clickup-mcp-server",
+    version: "0.1.0",
+}, {
+    capabilities: {
+        resources: {},
+        tools: {},
+        prompts: {},
+    },
+});
+/**
+ * Handler for listing available ClickUp tasks as resources.
+ * Each task is exposed as a resource with:
+ * - A clickup:// URI scheme
+ * - JSON MIME type
+ * - Human readable name and description (including the task name and description)
+ */
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    try {
+        const spaces = await clickup.getSpaces(config.teamId);
+        const resources = [];
+        for (const space of spaces) {
+            const lists = await clickup.getLists(space.id);
+            for (const list of lists) {
+                const { tasks } = await clickup.getTasks(list.id);
+                resources.push(...tasks.map((task) => ({
+                    uri: `clickup://task/${task.id}`,
+                    mimeType: "application/json",
+                    name: task.name,
+                    description: task.description || `Task in ${list.name} (${space.name})`,
+                    tags: []
+                })));
+            }
+        }
+        return { resources };
+    }
+    catch (error) {
+        console.error('Error listing resources:', error);
+        throw error;
+    }
+});
+/**
+ * Handler for reading the contents of a specific ClickUp task.
+ * Takes a clickup:// URI and returns the task content as JSON.
+ */
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    try {
+        const url = new URL(request.params.uri);
+        const taskId = url.pathname.replace(/^\/task\//, '');
+        const task = await clickup.getTask(taskId);
+        return {
+            contents: [{
+                    uri: request.params.uri,
+                    mimeType: "application/json",
+                    text: JSON.stringify(task, null, 2),
+                    tags: []
+                }]
+        };
+    }
+    catch (error) {
+        console.error('Error reading resource:', error);
+        throw error;
+    }
+});
+/**
+ * Handler that lists available tools.
+ * Exposes tools for listing spaces, creating tasks, and updating tasks.
+ */
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: "list_spaces",
+                description: "List all spaces and their lists with IDs",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                    required: []
+                }
+            },
+            {
+                name: "create_task",
+                description: "Create a new task in ClickUp",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        listId: {
+                            type: "string",
+                            description: "ID of the list to create the task in"
+                        },
+                        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 of the task (1-4)"
+                        },
+                        dueDate: {
+                            type: "string",
+                            description: "Due date of the task (ISO string)"
+                        }
+                    },
+                    required: ["listId", "name"]
+                }
+            },
+            {
+                name: "update_task",
+                description: "Update an existing task in ClickUp",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        taskId: {
+                            type: "string",
+                            description: "ID of the task to update"
+                        },
+                        name: {
+                            type: "string",
+                            description: "New name of the task"
+                        },
+                        description: {
+                            type: "string",
+                            description: "New description of the task"
+                        },
+                        status: {
+                            type: "string",
+                            description: "New status of the task"
+                        },
+                        priority: {
+                            type: "number",
+                            description: "New priority of the task (1-4)"
+                        },
+                        dueDate: {
+                            type: "string",
+                            description: "New due date of the task (ISO string)"
+                        }
+                    },
+                    required: ["taskId"]
+                }
+            }
+        ]
+    };
+});
+/**
+ * Handler for the CallToolRequestSchema.
+ * Handles the execution of tools like listing spaces, creating tasks, and updating tasks.
+ */
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    try {
+        switch (request.params.name) {
+            case "list_spaces": {
+                const spaces = await clickup.getSpaces(config.teamId);
+                const allLists = await clickup.getAllLists(config.teamId);
+                let output = "Available Spaces and Lists:\n\n";
+                for (const space of spaces) {
+                    output += `Space: ${space.name} (ID: ${space.id})\n`;
+                    const spaceLists = allLists.filter(list => list.space.id === space.id);
+                    for (const list of spaceLists) {
+                        const { statuses } = await clickup.getTasks(list.id);
+                        output += `  └─ List: ${list.name} (ID: ${list.id})\n`;
+                        output += `    Available Statuses: ${statuses.join(', ')}\n`;
+                    }
+                    output += "\n";
+                }
+                // Add lists without spaces at the end
+                const listsWithoutSpace = allLists.filter(list => !list.space);
+                if (listsWithoutSpace.length > 0) {
+                    output += "Lists without assigned spaces:\n";
+                    for (const list of listsWithoutSpace) {
+                        const { statuses } = await clickup.getTasks(list.id);
+                        output += `  └─ List: ${list.name} (ID: ${list.id})\n`;
+                        output += `    Available Statuses: ${statuses.join(', ')}\n`;
+                    }
+                }
+                return {
+                    content: [{
+                            type: "text",
+                            text: output
+                        }]
+                };
+            }
+            case "create_task": {
+                const args = request.params.arguments;
+                if (!args.listId || !args.name) {
+                    throw new Error("listId and name are required");
+                }
+                const { listId, ...taskData } = args;
+                const task = await clickup.createTask(listId, taskData);
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Created task ${task.id}: ${task.name}`
+                        }]
+                };
+            }
+            case "update_task": {
+                const args = request.params.arguments;
+                if (!args.taskId) {
+                    throw new Error("taskId is required");
+                }
+                const { taskId, ...updateData } = args;
+                const task = await clickup.updateTask(taskId, updateData);
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Updated task ${task.id}: ${task.name}`
+                        }]
+                };
+            }
+            default:
+                throw new Error("Unknown tool");
+        }
+    }
+    catch (error) {
+        console.error('Error handling tool call:', error);
+        throw error;
+    }
+});
+/**
+ * Add handlers for listing and getting prompts.
+ * Prompts include summarizing tasks, analyzing priorities, and generating task descriptions.
+ */
+server.setRequestHandler(ListPromptsRequestSchema, async () => {
+    return {
+        prompts: [
+            {
+                name: "summarize_tasks",
+                description: "Summarize all tasks in a list",
+            },
+            {
+                name: "analyze_priorities",
+                description: "Analyze task priorities and suggest optimizations",
+            },
+            {
+                name: "generate_description",
+                description: "Generate a detailed description for a task",
+            }
+        ]
+    };
+});
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    try {
+        switch (request.params.name) {
+            case "summarize_tasks": {
+                const spaces = await clickup.getSpaces(config.teamId);
+                const tasks = [];
+                // Gather all tasks
+                for (const space of spaces) {
+                    const lists = await clickup.getLists(space.id);
+                    for (const list of lists) {
+                        const { tasks: listTasks } = await clickup.getTasks(list.id);
+                        tasks.push(...listTasks.map((task) => ({
+                            type: "resource",
+                            resource: {
+                                uri: `clickup://task/${task.id}`,
+                                mimeType: "application/json",
+                                text: JSON.stringify(task, null, 2)
+                            }
+                        })));
+                    }
+                }
+                return {
+                    messages: [
+                        {
+                            role: "user",
+                            content: {
+                                type: "text",
+                                text: "Please provide a summary of the following ClickUp tasks:"
+                            }
+                        },
+                        ...tasks.map(task => ({
+                            role: "user",
+                            content: task
+                        })),
+                        {
+                            role: "user",
+                            content: {
+                                type: "text",
+                                text: "Please provide:\n1. A high-level overview of all tasks\n2. Group them by status\n3. Highlight any urgent or high-priority items\n4. Suggest any task dependencies or relationships"
+                            }
+                        }
+                    ]
+                };
+            }
+            case "analyze_priorities": {
+                const spaces = await clickup.getSpaces(config.teamId);
+                const tasks = [];
+                for (const space of spaces) {
+                    const lists = await clickup.getLists(space.id);
+                    for (const list of lists) {
+                        const { tasks: listTasks } = await clickup.getTasks(list.id);
+                        tasks.push(...listTasks.map((task) => ({
+                            type: "resource",
+                            resource: {
+                                uri: `clickup://task/${task.id}`,
+                                mimeType: "application/json",
+                                text: JSON.stringify(task, null, 2)
+                            }
+                        })));
+                    }
+                }
+                return {
+                    messages: [
+                        {
+                            role: "user",
+                            content: {
+                                type: "text",
+                                text: "Please analyze the priorities of the following ClickUp tasks:"
+                            }
+                        },
+                        ...tasks.map(task => ({
+                            role: "user",
+                            content: task
+                        })),
+                        {
+                            role: "user",
+                            content: {
+                                type: "text",
+                                text: "Please provide:\n1. Analysis of current priority distribution\n2. Identify any misaligned priorities\n3. Suggest priority adjustments\n4. Recommend task sequencing based on priorities"
+                            }
+                        }
+                    ]
+                };
+            }
+            case "generate_description": {
+                return {
+                    messages: [
+                        {
+                            role: "user",
+                            content: {
+                                type: "text",
+                                text: "Please help me generate a detailed description for a ClickUp task. The description should include:\n1. Clear objective\n2. Success criteria\n3. Required resources\n4. Dependencies\n5. Potential risks\n\nPlease ask me about the task details."
+                            }
+                        }
+                    ]
+                };
+            }
+            default:
+                throw new Error("Unknown prompt");
+        }
+    }
+    catch (error) {
+        console.error('Error handling prompt:', error);
+        throw error;
+    }
+});
+/**
+ * Start the server using stdio transport.
+ * This allows the server to communicate via standard input/output streams.
+ */
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error("Server error:", error);
+    process.exit(1);
+});

package/build/services/clickup.js

@@ -0,0 +1,70 @@
+import axios from 'axios';
+export class ClickUpService {
+    client;
+    static instance;
+    constructor(apiKey) {
+        this.client = axios.create({
+            baseURL: 'https://api.clickup.com/api/v2',
+            headers: {
+                'Authorization': apiKey,
+                'Content-Type': 'application/json'
+            }
+        });
+    }
+    static initialize(apiKey) {
+        if (!ClickUpService.instance) {
+            ClickUpService.instance = new ClickUpService(apiKey);
+        }
+        return ClickUpService.instance;
+    }
+    static getInstance() {
+        if (!ClickUpService.instance) {
+            throw new Error('ClickUpService not initialized. Call initialize() first.');
+        }
+        return ClickUpService.instance;
+    }
+    // Tasks
+    async getTasks(listId) {
+        const response = await this.client.get(`/list/${listId}/task`);
+        const tasks = response.data.tasks;
+        const statuses = [...new Set(tasks.map((task) => task.status.status))];
+        return { tasks, statuses };
+    }
+    async getTask(taskId) {
+        const response = await this.client.get(`/task/${taskId}`);
+        return response.data;
+    }
+    async createTask(listId, data) {
+        const response = await this.client.post(`/list/${listId}/task`, data);
+        return response.data;
+    }
+    async updateTask(taskId, data) {
+        const response = await this.client.put(`/task/${taskId}`, data);
+        return response.data;
+    }
+    async deleteTask(taskId) {
+        await this.client.delete(`/task/${taskId}`);
+    }
+    // Lists
+    async getLists(spaceId) {
+        const response = await this.client.get(`/space/${spaceId}/list`);
+        return response.data.lists;
+    }
+    async getAllLists(teamId) {
+        const response = await this.client.get(`/team/${teamId}/list`);
+        return response.data.lists;
+    }
+    async getList(listId) {
+        const response = await this.client.get(`/list/${listId}`);
+        return response.data;
+    }
+    // Spaces
+    async getSpaces(teamId) {
+        const response = await this.client.get(`/team/${teamId}/space`);
+        return response.data.spaces;
+    }
+    async getSpace(spaceId) {
+        const response = await this.client.get(`/space/${spaceId}`);
+        return response.data;
+    }
+}

package/build/types/clickup.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@taazkareem/clickup-mcp-server",
+  "version": "0.1.7",
+  "description": "ClickUp MCP Server - Integrate ClickUp tasks with AI through Model Context Protocol",
+  "type": "module",
+  "main": "build/index.js",
+  "bin": {
+    "clickup-mcp-server": "build/index.js"
+  },
+  "files": [
+    "build",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
+    "start": "node build/index.js",
+    "dev": "tsc -w",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm test",
+    "test": "echo \"No tests specified\" && exit 0"
+  },
+  "keywords": [
+    "clickup",
+    "mcp",
+    "ai",
+    "tasks",
+    "project-management",
+    "model-context-protocol",
+    "clickup-server",
+    "clickup-mcp-server"
+  ],
+  "author": "Talib Kareem",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/taazkareem/clickup-mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/taazkareem/clickup-mcp-server/issues"
+  },
+  "homepage": "https://github.com/taazkareem/clickup-mcp-server#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "0.6.0",
+    "axios": "^1.6.7",
+    "dotenv": "^16.4.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.16",
+    "typescript": "^5.3.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}