deploy-a-clickup-mcp

Enterprise ClickUp MCP server for the Deploy-A consulting ecosystem. 187 tools across 7 tiers + 5 MCP prompts + 2 resources. Features AI-powered workspace advisor, Workspace-as-Code, tiered loading, Discovery cache, markdown DSL for bulk scaffolding, and 10 industry blueprints.

Feature Comparison

| Feature | This MCP | Official ClickUp | taazkareem | Chykalophia | |---------|----------|------------------|------------|-------------| | Tools | 187 | ~49 | 150+ | 177+ | | Tier system | Yes (7 tiers) | No | Yes | No | | Workspace advisor | Yes (31 tools) | No | No | No | | Maturity scoring | Yes | No | No | No | | Fit-gap / DVA | Yes | No | No | No | | Industry blueprints | 10 | No | No | No | | Workspace-as-Code | Yes | No | No | No | | Markdown DSL bulk scaffolding | Yes (list_dsl_*) | No | No | No | | Discovery cache (bootstrap) | Yes (atomic + dedup) | No | No | No | | Idempotency keys | Yes (SHA-256 per session) | No | No | No | | Compact projections by default | Yes (workspace/spaces/folders/tasks) | No | No | No | | Response budget enforcer | Yes (75 KB cap + truncation honesty) | No | No | No | | Natural language dates | Yes (EN/ES) | No | No | No | | Name resolution | Yes (fuzzy, null-safe) | No | No | No | | Circuit breaker | Yes (per-endpoint) | Unknown | No | No | | Auth | API Key + OAuth 2.1 | OAuth only | OAuth + Key | API Key | | Rate limiting | Plan-aware (40-1500 req/min) | Fixed | Fixed | Fixed | | Price | Internal | Free (50-300/day) | $9/mo | Free |

Quick Start

git clone https://github.com/Bananoman/ClickUpMCP.git
cd ClickUpMCP
npm install
npm run build

Claude Desktop config

{
  "mcpServers": {
    "clickup_xma": {
      "command": "node",
      "args": ["/absolute/path/to/ClickUpMCP/dist/index.js"],
      "env": {
        "CLICKUP_API_KEY": "pk_your_key_here",
        "CLICKUP_TEAM_ID": "9017295843",
        "CLICKUP_PLAN": "enterprise",
        "CLICKUP_TOOL_TIERS": "core,discovery,extended,people,advisor,templates,dsl"
      }
    }
  }
}

Claude Code

# 1. Register (env is added in step 2 — the `-e` flag is variadic and consumes trailing args)
claude mcp add clickup_xma --scope user -- node "$(pwd)/dist/index.js"

# 2. Edit ~/.claude.json and add the env block under mcpServers.clickup_xma:
#    "env": { "CLICKUP_API_KEY": "...", "CLICKUP_TEAM_ID": "...",
#             "CLICKUP_PLAN": "enterprise",
#             "CLICKUP_TOOL_TIERS": "core,discovery,extended,people,advisor,templates,dsl" }

Consultants: the canonical install runbook lives in the Xmarts Genius Brain. Ask query_knowledge("install ClickUp MCP") from any Claude Code session.

Tier system

Solve the "too many tools" problem — LLMs degrade past ~25 tools. Tools are organized in 7 tiers, loaded on demand via CLICKUP_TOOL_TIERS.

| Tier | Tools | Default? | Unlocks | |------|------:|----------|---------| | core | 16 | always | task/list/folder/space CRUD + search + entry-point reads | | discovery | 2 | always | resolve_entity, refresh_discovery_cache | | dsl | 3 | recommended | list_dsl_apply — atomic subtask scaffolding via markdown DSL | | people | 16 | opt-in | members, guests, user groups, find_member_by_name, workspace switching | | extended | 108 | opt-in | comments, time-tracking, custom-field CRUD, tags, views, attachments, docs, chat, dependencies, sprints | | templates | 11 | opt-in | bulk_create_tasks, bulk_update_tasks, bulk_move, composite ops | | advisor | 31 | opt-in | analyze_workspace, assess_maturity, fit-gap, bottlenecks, automation blueprints |

# Minimal — entry-point CRUD only (~21 tools, recommended when you know exactly what you need)
CLICKUP_TOOL_TIERS=core,discovery,dsl

# Audit-ready (~142 tools) — adds sentiment, time, members, full collaboration
CLICKUP_TOOL_TIERS=core,discovery,extended,people

# Full surface (~187 tools, recommended default for consultants)
CLICKUP_TOOL_TIERS=core,discovery,extended,people,advisor,templates,dsl

Default if CLICKUP_TOOL_TIERS is unset: ALL tiers (backwards compat).

Tools (187)

Full autogenerated catalog with descriptions: docs/TOOLS.md. The list below is a navigational snapshot per domain — domain ≠ tier (e.g. get_task_comments is domain collaboration but tier extended).

Workspace (19)

get_workspace get_task_members get_list_members find_member_by_name invite_guest get_guest remove_guest add_guest_to_task add_guest_to_list add_guest_to_folder get_user_groups create_user_group update_user_group delete_user_group get_roles resolve_name search_workspace_entity get_clickup_guide parse_date

Hierarchy (17)

get_spaces get_space create_space update_space delete_space get_folders get_folder create_folder update_folder delete_folder get_lists get_folderless_lists get_list create_list create_folderless_list update_list delete_list

Tasks (20)

get_task create_task update_task delete_task get_tasks search_tasks move_task add_task_to_list duplicate_task create_subtask get_task_time_in_status get_list_time_in_status get_task_templates create_from_template get_custom_task_types create_checklist update_checklist delete_checklist create_checklist_item update_checklist_item delete_checklist_item add_dependency delete_dependency add_task_link delete_task_link find_dependency_chain get_task_dependencies get_sprints create_sprint get_sprint_report

Collaboration (26)

get_task_comments create_task_comment update_comment delete_comment get_threaded_replies get_list_comments create_list_comment get_space_tags create_space_tag edit_space_tag delete_space_tag add_tag_to_task remove_tag_from_task create_custom_field delete_custom_field get_list_fields set_custom_field_value remove_custom_field_value get_team_views get_space_views get_folder_views get_list_views get_view get_view_tasks delete_view create_view update_view get_chat_channels send_chat_message get_task_attachments upload_attachment_from_url

Tracking (16)

get_goals get_goal create_goal update_goal delete_goal create_key_result update_key_result delete_key_result get_time_entries get_task_time_entries create_time_entry update_time_entry delete_time_entry get_running_timer start_timer stop_timer

Automation (4)

get_webhooks create_webhook update_webhook delete_webhook

Bulk Operations (11)

bulk_create_tasks bulk_update_tasks bulk_move_tasks bulk_delete_tasks bulk_add_tags bulk_set_assignees bulk_set_due_dates create_project_structure archive_completed_tasks clone_list_tasks get_workspace_summary

Docs (5)

search_docs create_doc get_doc_pages create_doc_page update_doc_page

Advisor (28)

analyze_workspace analyze_list_health detect_workspace_industry generate_automation_blueprint compare_spaces onboard_client_workspace generate_time_report find_bottlenecks audit_custom_field_usage diagnose_and_fix setup_space_from_blueprint get_completion_trend preview_status_change overview_all_spaces detect_duplicate_fields find_zombie_subtasks get_clickup_brain_capabilities assess_clickup_maturity generate_fitgap_analysis generate_implementation_plan estimate_automation_savings create_implementation_templates export_space_config import_space_config get_workload_distribution detect_status_inconsistencies get_sprint_report find_dependency_chain

MCP Prompts (5)

clickup_discovery_session clickup_fitgap_analysis clickup_implementation_plan clickup_health_check clickup_automation_planner

MCP Resources (2)

clickup://workspace/{teamId}/overview clickup://workspace/{teamId}/lists

Architecture

Tool Handler -> ID Coercion -> Zod Validation -> Response Cache
  -> Bottleneck Rate Limiter -> Circuit Breaker -> axios + retry -> ClickUp API v2

• Persona filtering: 6 presets from 20 to 161 tools
• Plan-aware rate limiting: free (100/min) to enterprise (10000/min)
• TTL caching: 1hr for workspaces, 30min for spaces, 5min for lists, 1min for tasks
• Circuit breaker: Opens after 50% failure rate, 30s recovery
• Compact mode: Strips nulls, truncates descriptions, reduces token usage
• Deferred loading: efficient mode loads 15 core tools, defers rest
• ID coercion: Auto-converts numeric IDs to strings (prevents MCP framework type issues)

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | CLICKUP_API_KEY | Yes* | -- | API key (pk_...) | | CLICKUP_OAUTH_CLIENT_ID | Yes* | -- | OAuth 2.1 client ID (alternative to API key) | | CLICKUP_PERSONA | No | project_manager | Persona preset | | CLICKUP_PLAN | No | enterprise | ClickUp plan tier | | CLICKUP_DOMAINS | No | all | Domain filter | | CLICKUP_TOOL_MODE | No | full | full, efficient, minimal | | CLICKUP_RESPONSE_MODE | No | compact | full or compact | | CLICKUP_ENABLED_TOOLS | No | -- | Comma-separated tool whitelist | | CLICKUP_CACHE_TTL | No | 300 | Default cache TTL (seconds) | | LOG_LEVEL | No | info | debug, info, warn, error |

*One of API key or OAuth is required.

Industry Playbooks

The advisor supports 10 industries with complete blueprints (statuses, custom fields, automations):

marketing software consulting operations recruiting healthcare finance legal education real_estate

Development

npm run build     # Compile TypeScript
npm test          # Run 176 tests (14 suites)
npm run lint      # Type check (tsc --noEmit)
npm run dev       # Watch mode
./scripts/verify-production.sh  # Pre-flight check

Documentation

• QUICK-START.md -- 3-minute setup guide
• USE-CASES.md -- 10 high-impact use cases with examples
• CLAUDE.md -- Project constitution
• CONTRIBUTING.md -- Contributor guide
• DEPLOYMENT.md -- Setup for consultants
• docs/HOW-TO-BUILD-AN-MCP-SERVER.md -- MCP creation guide
• docs/COMPETITIVE-ANALYSIS.md -- vs official + community MCPs

License

MIT