Customize: ClickUp-specific README, tools, and docs (8 tools, PM workflows, MCPEngage branding)

2026-02-02 06:59:49 -05:00 · 2026-02-02 06:59:49 -05:00 · c57d17cda7
commit c57d17cda7
parent d588831999
2 changed files with 145 additions and 53 deletions
--- 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).
--- 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 <hello@mcpengage.com>",
+  "author": "MCPEngage <hello@mcpengage.com>",
  "license": "MIT",
  "repository": {
    "type": "git",