From c57d17cda7a440a76d9e9b7244cb271966f7e84e Mon Sep 17 00:00:00 2001 From: Jake Shore Date: Mon, 2 Feb 2026 06:59:49 -0500 Subject: [PATCH] Customize: ClickUp-specific README, tools, and docs (8 tools, PM workflows, MCPEngage branding) --- README.md | 196 +++++++++++++++++++++++++++++++++++++-------------- package.json | 2 +- 2 files changed, 145 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index ae72c11..f9ef8ea 100644 --- a/README.md +++ b/README.md @@ -8,30 +8,62 @@ ## πŸ’‘ What This Unlocks -**This MCP server gives AI direct access to your entire ClickUp workspace.** Instead of clicking through interfaces, you just *tell* it what you need. +**This MCP server gives AI direct access to your entire ClickUp workspace.** Instead of clicking through tasks, lists, and spaces manually, you just *tell* Claude what you needβ€”and it executes instantly across your entire project management workflow. -### 🎯 ClickUp-Native Power Moves +### 🎯 ClickUp-Specific Power Moves -The AI can directly control your ClickUp account with natural language: +The AI can directly control your ClickUp workspace with natural language. Here are **5 real workflows** using the actual tools in this MCP server: -- **Smart automation** β€” Complex workflows in plain English -- **Data intelligence** β€” Query, analyze, and export your ClickUp data -- **Rapid operations** β€” Bulk actions that would take hours manually -- **Cross-platform integration** β€” Combine ClickUp with other tools seamlessly +1. **πŸ”₯ Sprint Planning Automation** + - AI uses `list_spaces` β†’ `list_lists` β†’ `list_tasks` to audit your entire workspace structure + - Identifies overdue tasks, calculates sprint velocity, and auto-creates new tasks with `create_task` for next sprint + - *"Show me all overdue tasks in Marketing space, calculate team velocity, and create next week's sprint tasks"* -### πŸ”— The Real Power: Combining Tools +2. **⏱️ Time Tracking Intelligence** + - AI calls `get_time_entries` with date ranges to pull all tracked time across projects + - Generates burndown reports, identifies bottlenecks, and flags under-logged tasks + - *"Pull time entries for Q1, show which tasks took longer than estimated, and flag team members under 30 hours"* -AI can chain multiple ClickUp operations together: +3. **πŸ“‹ Bulk Task Operations** + - AI uses `list_tasks` with filters (status, assignee, due date) to find matching tasks + - Batch updates with `update_task` (reassign, reprioritize, reschedule) across dozens of tasks in seconds + - *"Find all 'In Progress' tasks assigned to Sarah with due dates this week, reassign to Tom, and push due dates by 3 days"* -- Query data β†’ Filter results β†’ Generate reports -- Search records β†’ Update fields β†’ Notify team -- Analyze metrics β†’ Create tasks β†’ Schedule follow-ups +4. **πŸ”” Smart Status Reporting** + - AI chains `list_tasks` β†’ `get_task` (with subtasks) β†’ `add_comment` to generate weekly status updates + - Calculates completion rates, flags blockers, and posts summary comments to leadership tasks + - *"Generate weekly status report for Product Launch project, identify blockers, and post summary comment to executive task"* + +5. **🎯 Priority Triage Workflow** + - AI uses `list_tasks` filtered by priority and due dates to surface urgent work + - Calls `update_task` to adjust priorities based on dependencies and deadlines + - Posts updates via `add_comment` to notify team of priority shifts + - *"Show all P1 tasks due in next 48 hours, escalate any with incomplete dependencies, and notify assignees via comments"* + +### πŸ”— The Real Power: Chaining Operations + +AI doesn't just execute single commandsβ€”it orchestrates **multi-step workflows**: + +- **Workspace Audit** β†’ `list_spaces` β†’ `list_lists` β†’ `list_tasks` (all statuses) β†’ Generate health report +- **Task Migration** β†’ `list_tasks` (source list) β†’ `create_task` (destination list) β†’ `update_task` (archive source) +- **Time Analysis** β†’ `get_time_entries` (filtered by assignee) β†’ Cross-reference with `list_tasks` β†’ Flag discrepancies ## πŸ“¦ What's Inside -**112 API tools** covering the entire ClickUp platform (Project Management). +**8 production-ready ClickUp API tools** covering core project management operations: -All with proper error handling, automatic authentication, and TypeScript types. +| Tool | Purpose | +|------|---------| +| `list_spaces` | List all spaces in your workspace/team | +| `list_lists` | Get lists from folders or spaces (folderless) | +| `list_tasks` | Query tasks with filters (status, assignee, dates, pagination) | +| `get_task` | Fetch detailed task info (including subtasks) | +| `create_task` | Create new tasks with full metadata (assignees, tags, dates, priority) | +| `update_task` | Update existing tasks (name, description, status, assignees, dates) | +| `add_comment` | Add comments to tasks (supports markdown, assignee tagging) | +| `get_time_entries` | Pull time tracking data with filters (user, date range, task/list/space) | + +All tools include proper error handling, automatic authentication, and full TypeScript types. ## πŸš€ Quick Start @@ -45,7 +77,11 @@ All with proper error handling, automatic authentication, and TypeScript types. npm run build ``` -2. **Get your ClickUp API credentials** (see Authentication section below) +2. **Get your ClickUp API token:** + - Go to your ClickUp workspace β†’ **Settings** (bottom left) + - Navigate to **My Settings** β†’ **Apps** + - Click **Generate** under "API Token" section + - Copy the token (starts with `pk_`) 3. **Configure Claude Desktop:** @@ -58,56 +94,75 @@ All with proper error handling, automatic authentication, and TypeScript types. "mcpServers": { "clickup": { "command": "node", - "args": ["/ABSOLUTE/PATH/TO/clickup-mcp/dist/index.js"], + "args": ["/ABSOLUTE/PATH/TO/clickup-mcp-2026-complete/dist/index.js"], "env": { - "CLICKUP_API_KEY": "your-api-key-here" + "CLICKUP_API_KEY": "pk_your_token_here" } } } } ``` -4. **Restart Claude Desktop** +4. **Restart Claude Desktop** β€” the πŸ”Œ icon in the bottom right should show "clickup" connected ### Option 2: Deploy to Railway [![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/clickup-mcp) 1. Click the button above -2. Set your ClickUp API credentials in Railway dashboard -3. Use the Railway URL as your MCP server endpoint +2. Set your `CLICKUP_API_KEY` environment variable in Railway dashboard +3. Use the Railway URL as your MCP server endpoint in remote Claude configurations ### Option 3: Docker ```bash docker build -t clickup-mcp . docker run -p 3000:3000 \ - -e CLICKUP_API_KEY=your-key \ + -e CLICKUP_API_KEY=pk_your_token_here \ clickup-mcp ``` ## πŸ” Authentication -See the official [ClickUp API documentation](https://docs.clickup.com) for authentication details. +**ClickUp uses personal API tokens** for authentication (no OAuth required). -The MCP server handles token refresh automatically. +- **Get your token:** ClickUp Settings β†’ My Settings β†’ Apps β†’ Generate API Token +- **Format:** Starts with `pk_` followed by 48 characters +- **Permissions:** Token inherits your user permissions in the workspace +- **Security:** Store securely; token grants full API access to your ClickUp data -## 🎯 Example Prompts +πŸ“– **Official docs:** [ClickUp API Authentication](https://clickup.com/api/developer-portal/authentication/) -Once connected to Claude, you can use natural language. Examples: +The MCP server handles authentication automaticallyβ€”just set `CLICKUP_API_KEY` in your environment. -- *"Show me recent activity in ClickUp"* -- *"Create a new record with these details..."* -- *"Export all data from last month"* -- *"Update the status of X to Y"* -- *"Generate a report of..."* +## 🎯 Example Prompts for Project Management + +Once connected to Claude, use these natural language prompts: + +**Sprint Planning:** +- *"Show me all active tasks in the Engineering space, group by assignee, and identify anyone over 40 hours this sprint"* +- *"Create 5 tasks for next sprint: API integration, UI design, database migration, testing, and deploymentβ€”assign to the usual team"* + +**Task Management:** +- *"Find all P1 tasks in the Product space due this week and show me their current status"* +- *"Update task #abc123 to status 'In Review', add Sarah as assignee, and set due date to Friday"* +- *"List all tasks with 'blocked' in the description, add a comment asking for updates, and bump priority to urgent"* + +**Time Tracking & Reporting:** +- *"Pull all time entries for the Marketing team from last month and generate a summary report"* +- *"Show me which tasks have the most time logged but are still marked 'In Progress'"* +- *"Get time entries for user ID abc123 for this week and compare to their assigned task estimates"* + +**Workspace Intelligence:** +- *"Audit my entire workspace: show spaces, lists in each space, task counts, and flag any lists with 0 tasks or 50+ tasks"* +- *"Find all tasks created in the last 7 days across all spaces and summarize what the team is working on"* ## πŸ› οΈ Development ### Prerequisites - Node.js 18+ - npm or yarn -- ClickUp account with API access +- ClickUp workspace with API access ### Setup @@ -116,7 +171,7 @@ git clone https://github.com/BusyBee3333/ClickUp-MCP-2026-Complete.git cd clickup-mcp-2026-complete npm install cp .env.example .env -# Edit .env with your ClickUp credentials +# Edit .env with your ClickUp API token (pk_...) npm run build npm start ``` @@ -129,44 +184,81 @@ npm run test:watch # Watch mode npm run test:coverage # Coverage report ``` +### Project Structure + +``` +clickup-mcp-2026-complete/ +β”œβ”€β”€ src/ +β”‚ └── index.ts # Main MCP server + ClickUp API client +β”œβ”€β”€ dist/ # Compiled JavaScript (after build) +β”œβ”€β”€ package.json +β”œβ”€β”€ tsconfig.json +└── .env.example +``` + ## πŸ› Troubleshooting -### "Authentication failed" -- Verify your API credentials are correct -- Check that your API key hasn't been revoked -- Ensure you have the necessary permissions +### "Authentication failed" or 401 errors +- Verify your API token starts with `pk_` and is exactly 50 characters +- Check token wasn't revoked in ClickUp Settings β†’ Apps +- Ensure your user has access to the workspace/space you're querying ### "Tools not appearing in Claude" -- Restart Claude Desktop after updating config -- Check that the path in `claude_desktop_config.json` is absolute -- Verify the build completed successfully (`dist/index.js` exists) +- Restart Claude Desktop after updating `claude_desktop_config.json` +- Verify the path in config is **absolute** (not relative) +- Check that `dist/index.js` exists after running `npm run build` +- Look at Claude Desktop logs: macOS `~/Library/Logs/Claude/mcp*.log` + +### "Rate limit exceeded" +- ClickUp API has rate limits (100 requests/min for free, higher for paid) +- The MCP server doesn't implement retry logic yetβ€”add delays between bulk operations +- Consider upgrading your ClickUp plan for higher limits + +### Tasks not filtering correctly +- `list_tasks` uses ClickUp's query parameter syntaxβ€”check [ClickUp API docs](https://clickup.com/api/clickupreference/operation/GetTasks/) for exact filter formats +- Status names are **case-sensitive** and must match your workspace's custom statuses +- Assignee IDs are numeric user IDs (not email addresses)β€”use `list_users` tool if available or check ClickUp UI ## πŸ“– Resources -- [ClickUp API Documentation](https://docs.clickup.com) -- [MCP Protocol Specification](https://modelcontextprotocol.io/) -- [Claude Desktop Documentation](https://claude.ai/desktop) +- **[ClickUp API Documentation](https://clickup.com/api/)** β€” Official REST API reference +- **[ClickUp API Portal](https://clickup.com/api/developer-portal/)** β€” Generate tokens, view rate limits +- **[MCP Protocol Specification](https://modelcontextprotocol.io/)** β€” How MCP servers work +- **[Claude Desktop Documentation](https://claude.ai/desktop)** β€” Configure AI integrations ## 🀝 Contributing -Contributions are welcome! Please: +Contributions are welcome! Missing a ClickUp API endpoint you need? Want to add webhooks support? Open a PR. -1. Fork the repo -2. Create a feature branch (`git checkout -b feature/amazing-tool`) -3. Commit your changes (`git commit -m 'Add amazing tool'`) -4. Push to the branch (`git push origin feature/amazing-tool`) -5. Open a Pull Request +**How to contribute:** + +1. Fork this repo +2. Create a feature branch (`git checkout -b feature/add-custom-fields-support`) +3. Add your tool definition in `src/index.ts` (follow existing patterns) +4. Test locally with Claude Desktop +5. Commit your changes (`git commit -m 'Add custom fields tool'`) +6. Push to your fork (`git push origin feature/add-custom-fields-support`) +7. Open a Pull Request with details on what you added ## πŸ“„ License -MIT License - see [LICENSE](LICENSE) for details +MIT License - see [LICENSE](LICENSE) for details. + +You're free to use, modify, and distribute this MCP server for personal or commercial projects. ## πŸ™ Credits -Built by [MCPEngine](https://mcpengage.com) β€” AI infrastructure for business software. +Built by **[MCPEngage](https://mcpengage.com)** β€” AI infrastructure for business software. -Want more MCP servers? Check out our [full catalog](https://mcpengage.com) covering 30+ business platforms. +This server is part of the **MCPEngage 2026 Complete Series**, providing production-ready MCP servers for 30+ business platforms. + +**Want more?** Check out our full catalog: +- [Asana MCP Server](https://github.com/BusyBee3333/Asana-MCP-2026-Complete) β€” Project management +- [Jira MCP Server](https://github.com/BusyBee3333/Jira-MCP-2026-Complete) β€” Issue tracking +- [Trello MCP Server](https://github.com/BusyBee3333/Trello-MCP-2026-Complete) β€” Kanban boards +- [Wrike MCP Server](https://github.com/BusyBee3333/Wrike-MCP-2026-Complete) β€” Work management +- ...and 26 more at [mcpengage.com](https://mcpengage.com) --- -**Questions?** Open an issue or join our [Discord community](https://discord.gg/mcpengine). +**Questions?** Open an issue or join our [Discord community](https://discord.gg/mcpengage) (invite on mcpengine.pages.dev). diff --git a/package.json b/package.json index 8b6f50a..3854c62 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,7 @@ "description": "MCP server for ClickUp API - 2026 Complete Version", "type": "module", "main": "dist/index.js", - "author": "MCPEngine ", + "author": "MCPEngage ", "license": "MIT", "repository": { "type": "git",