The official ClickUp MCP server lets a compatible AI client search and work with native ClickUp data through OAuth, within the authorizing user’s permissions. Its endpoint is https://mcp.clickup.com/mcp. Use MCP when a person or agent needs to interpret context, search relevant records, summarize findings, or propose a reviewable change. Use the ClickUp API or Automations when the trigger, fields, timing, and expected result are fixed.
For example, MCP can help summarize blockers in a specified Sprint List and propose status changes. A controlled integration can then verify each task’s current status before an approved update. This guide covers connection, documented capabilities, rate limits, safe write patterns, practical workflows, and the decision between MCP, the API, and ClickUp Automations.
What the ClickUp MCP server does
MCP, or the Model Context Protocol, is a standard that lets an AI client invoke tools exposed by connected systems. ClickUp currently documents its official MCP server as available on all plans, including Free Forever, although plan availability and limits can change. The server works with native ClickUp data and does not use ClickUp Connected Search to retrieve content from external services such as Google Drive or Slack.
ClickUp’s current documentation describes a broad catalog covering Workspace search, task creation and updates, bulk task operations, Custom Fields, tags, links, dependencies, List movement, comments, time tracking, Workspace hierarchy and members, Docs, Chat, and time-in-status reporting. The catalog can change, so check the live ClickUp MCP tool catalog for current names and inputs rather than relying on a fixed tool count or schema.
Task deletion is currently documented in the tool catalog. Broader deletion capabilities for other ClickUp object types are not established consistently across the official documentation, so do not assume that MCP can delete every type of content.
Before connecting: check the client, account, and access
You need a ClickUp account, a compatible MCP client, OAuth authorization, and access to the target Workspace and objects. The official ClickUp MCP endpoint does not accept API keys or personal access tokens. The connected user’s ClickUp permissions determine what the client can read or change.
ClickUp provides setup instructions for several clients, including Claude, Claude Code, ChatGPT, Cursor, Devin, Microsoft Copilot Studio, VS Code, Windsurf, and Antigravity. This is not a guarantee that every MCP client uses the same configuration or that the list is permanent. Check ClickUp’s current client setup instructions for the client you plan to use.
A custom client has different requirements from an ordinary user connection. ClickUp documents JSON-RPC 2.0 over HTTP, OAuth 2.1 with PKCE, and MCP support for custom clients. If the client is not covered by ClickUp’s instructions, verify its current configuration requirements instead of copying fields from another client.
Connect a supported client and verify it
- Open the client’s MCP, connector, app, or developer settings.
- Add ClickUp using the official endpoint:
https://mcp.clickup.com/mcp. Use the configuration method documented for that client. - Complete ClickUp’s OAuth flow and authorize the relevant Workspace or Workspaces when the client supports that choice.
- Confirm that the connection is active and that ClickUp tools are available.
- Run a narrow read-only test, such as:
List the Spaces I can access in this Workspace.
- Compare the returned scope with the connected user’s expected access before attempting a write.
If OAuth succeeds but tools are missing, check the client’s current configuration instructions and authorization state. Multi-Workspace behavior depends on the client. Do not use a bulk edit or deletion to test a new connection.
The official ClickUp MCP overview covers the endpoint, OAuth model, availability, custom-client requirements, and documented usage behavior.
A safer write pattern: read, resolve, preview, write, verify
For a consequential change, use this operating sequence:
- Read: retrieve the relevant Space, Folder, List, task, comments, or other scope.
- Resolve: convert names into stable object IDs and return the surrounding context.
- Preview: show the exact records, fields, and values that would change.
- Approve: require confirmation for bulk, destructive, or externally visible changes.
- Write: apply only the approved IDs and fields.
- Verify: read the changed objects again and report actual successes and failures.
This is an integration recommendation, not a built-in ClickUp MCP approval feature. Names alone are weak targets because a Workspace may contain similarly named Lists, tasks, or users. Keep exact IDs, status checks, date filters, required fields, and permission checks in ordinary logic. Use AI for bounded interpretation such as summarizing comments, extracting blockers, or proposing a classification.
For task intake, the following is an illustrative output contract, not a ClickUp-provided schema:
{
"source_system": "support_portal",
"source_record_id": "BUG-8421",
"source_event_version": "3",
"target_list_id": "list_123",
"proposed_title": "Export fails for filtered reports",
"normalized_description": "Reproduction steps and observed result",
"candidate_assignee_id": "user_456",
"duplicate_candidate_ids": [],
"confidence": 0.91,
"requires_human_review": false
}Validate the List and assignee IDs, map severity or priority to approved values, and route low-confidence or duplicate-ambiguous cases to a person. For concurrent intake workers, deduplicate at the source-event grain with a database-enforced unique constraint or transactional upsert on a key such as source_system + source_record_id + source_event_version. A lookup followed by task creation is not race-safe when two workers can process the same event.
Store source provenance in an approved ClickUp field or an integration database. If the integration needs a detailed execution record, retain the authorizing user, Workspace and List IDs, timestamp, client or model identifier when available, policy version, and before-and-after values in that integration store. These controls are design choices, not native MCP features. Teams that need help defining permissions, fields, and operating controls can explore ClickUp consulting.
Three practical workflows and their control points
The workflows below are illustrative operating designs. They use documented ClickUp capabilities but are not vendor templates.
| Workflow | AI job | Validation and action | Fallback |
|---|---|---|---|
| Bug intake | Extract a proposed title, reproduction steps, component, severity, assignee, and possible duplicate tasks from one source report. | Check the immutable source key, target List and assignee IDs, approved priority mapping, and duplicate candidates before creating a task. | Send low-confidence or duplicate-ambiguous reports to the triage owner. |
| Sprint review | Summarize blockers and discussions for one specified Sprint List and propose status changes with reasons. | Preview exact task IDs, re-read current statuses, obtain approval, apply bounded updates, and verify each result. | Skip tasks changed since the preview and report partial failures individually. |
| Release notes | Group evidence-backed completed work into features, improvements, and fixes. | Filter scope, completion status, and dates deterministically. Require supporting task IDs for every bullet before saving or publishing. | Omit unsupported bullets or return the draft to an editor. |
Bug intake: one source report to one reviewed task
A support form or issue system supplies the report text, source URL, immutable record ID, received time, and attachment references. The integration selects the target List. The AI proposes normalized reproduction steps, affected component, severity, candidate assignee, and possible duplicate task IDs. Validation confirms that the target List and assignee exist and are accessible, checks the team’s approved severity mapping, and tests the source-event uniqueness key.
After approval, the integration can use documented task creation, task-field, tag, link, dependency, and comment capabilities to create a traceable task. Save the source record ID and URL with the task or in the integration store. If the same source record arrives again, update or surface the existing case rather than creating another task. Do not deduplicate only by title, date, prompt text, or text similarity.
The triage owner decides severity, assignment, duplicate resolution, and privacy handling. If concurrent workers are possible, enforce uniqueness in the database and use an atomic upsert. This prevents two workers from both passing a preliminary lookup and creating duplicate tasks.
Sprint review: propose changes, then re-check the work
A reviewer supplies one Sprint List ID, a cutoff timestamp, and any eligible status IDs. The client retrieves candidate tasks and relevant comments. Deterministic filters limit the scope by List, date, and status. AI summarizes blockers, overdue work, and unresolved discussions, then returns proposed changes with exact task IDs and reasons.
Before writing, show the proposed task IDs and status values and obtain approval. Re-read each current status immediately before mutation. Apply supported updates in bounded batches, then read the changed tasks again. If a person changed a task after the proposal, follow the team’s conflict rule and do not overwrite the newer value by default. Record successes and failures separately, and retry only operations confirmed not to have succeeded.
ClickUp documents task search, comments, bulk task operations, and updates. The preview, approval, re-read, batching, and concurrency controls are safeguards implemented around those capabilities.
Release notes: filter evidence before drafting
An editor starts a run for a defined Space or List, release version, completion-status rule, and date interval. The integration first filters tasks by scope, status, and completion time. AI then groups the selected work and drafts concise bullets. Every bullet must include supporting task IDs or links and an editorial flag when the evidence is incomplete.
Use a run key such as workspace_id + source_scope_id + normalized_start + normalized_end + release_version + run_number for the release-note run. Store task-level citations separately because one run can cover many tasks and one task can support multiple bullets. Exclude out-of-window or duplicate items, and omit any bullet without supporting task IDs. Require editorial approval before external publication.
The final draft can be saved in an appropriate ClickUp Doc or sent to an editor. ClickUp documents task search and Docs capabilities, while the run key, citation records, evidence rule, and approval process are proposed integration designs.
Rate limits: estimate tool calls, not prompts
One natural-language prompt can produce several tool calls, such as a search, multiple task reads, a comment lookup, an update, and a verification read. Estimate calls per run and multiply by expected concurrent runs. ClickUp says initialize and tools/list operations do not count toward the documented MCP usage limits.
Without Everything AI, ClickUp’s help page lists these rolling 24-hour allowances:
- Free Forever: 100 calls
- Unlimited: 300 calls
- Business: 1,000 calls
- Business Plus: 2,500 calls
- Enterprise: 5,000 calls
The developer documentation additionally lists Enterprise Plus at 25,000 calls per rolling 24 hours. With Everything AI, ClickUp says MCP uses API-style per-token, per-minute limits: 100 requests for Free Forever, Unlimited, and Business; 1,000 for Business Plus; and 10,000 for Enterprise and Enterprise Plus.
Important documentation conflict: ClickUp’s help page describes a shared Workspace pool for the non-Everything-AI allowance, while its developer page describes limits per Workspace and per client. Do not build a quota-dependent process around either interpretation until ClickUp confirms the rule for the applicable account. Plan conservatively, especially when several clients or workers may be active.
When usage is exhausted, ClickUp documents a RATE_LIMIT_EXCEEDED error and a retryAfter value. Honor returned retry guidance where available, reduce unnecessary reads, and avoid assuming that every client exposes the same HTTP representation. Check the current ClickUp MCP documentation before deployment.
MCP, the API, or ClickUp Automations?
- Use MCP for interactive investigation, contextual summaries, natural-language requests, and reviewable AI-assisted updates where the client must interpret several relevant ClickUp records.
- Use the API for custom applications, fixed field mappings, scheduled jobs, webhooks, synchronization, and higher-volume deterministic integrations. ClickUp’s public API supports personal API tokens or OAuth. Those credentials are separate from the official MCP endpoint. See the ClickUp API authentication documentation.
- Use ClickUp Automations when a predictable event-and-action rule fits the current product’s capabilities.
A practical decision test is simple: if the same event should always produce the same action, prefer API code or an Automation. If the request requires interpretation among several relevant records, MCP may fit. A hybrid design can use deterministic infrastructure to select a record and provide bounded context, AI to return a structured proposal, and validation or human approval before applying it.
The reviewed MCP documentation describes request-driven client interactions and does not establish a native MCP scheduler or event-monitoring mechanism. Use API, webhooks, or Automations for deterministic orchestration unless current ClickUp documentation confirms otherwise. For implementation planning, see ClickUp setup and automation.
Inbound ClickUp MCP and outbound external MCP connections are different
The official endpoint above lets an external AI client work with ClickUp. Separately, ClickUp Brain and Super Agents can connect outward to external MCP servers. The external server must have a public URL, and ClickUp documents OAuth, API key, or no-auth options depending on the provider.
Workspace-wide external connections are an administrative setup. Personal connections may be available to members when the relevant permission is enabled. ClickUp currently describes external MCP connections as available on all plans for a limited time, so do not treat that availability as a permanent plan guarantee.
Before connecting an external provider:
- Verify the public endpoint and authentication requirements.
- Choose personal or Workspace-wide scope deliberately.
- Expose only the tools required for the intended task.
- Review the provider’s data handling, retention, and logging terms.
- Test a read-only operation before enabling write tools.
- Assign an owner to review connection changes and available audit-log coverage.
ClickUp says Workspace audit logs include setup, update, and disconnection events for external MCP connections. This does not establish a complete log of every inbound MCP prompt or tool call. ClickUp also says outbound IP addresses are dynamic, so do not design an external connection around fixed ClickUp IP allowlisting. See the official guide to connecting an MCP server to a Workspace.
Troubleshoot with scope and evidence
- OAuth succeeds but tools are missing: re-check the client’s current ClickUp configuration, authorization state, and support for the connection method.
- Search is empty or incomplete: test a narrow Space, Folder, List, or date range, then confirm that the connected user can access the target objects.
- A write is denied: confirm the target ID and the authorizing user’s permission. Do not substitute a similarly named object.
- A write times out: read the target again before retrying. A timeout does not prove that the change failed.
- A rate limit is returned: reduce unnecessary calls and follow the retry guidance supplied by the response, if present.
For any failed or ambiguous mutation, verify the target state first. Then report success, retry a confirmed failure, or send the case to an operator.
Frequently asked questions
Does ClickUp MCP respect Workspace permissions?
Yes. The connected user’s permissions constrain what the AI client can access and change.
Can ClickUp MCP search Google Drive or Slack through Connected Search?
No. ClickUp’s help documentation says MCP cannot use Connected Search for external applications such as Google Drive or Slack. ClickUp’s outbound external MCP feature is a separate integration direction.
Can I use an API token with the official ClickUp MCP server?
No. The official endpoint uses OAuth. API tokens or OAuth are separate authentication options for ClickUp’s public API.
Can MCP delete tasks?
The current tool catalog documents task deletion. Do not generalize that capability to every ClickUp object type because official documentation is not consistent about broader deletion support.
Can MCP run a scheduled workflow by itself?
The reviewed documentation does not establish a native MCP scheduler or event monitor. Use an API, webhook, or ClickUp Automation for deterministic orchestration, and add an AI step only where interpretation is needed.
Can one client authorize multiple Workspaces?
The OAuth flow allows Workspace selection in supported clients, but the exact multi-Workspace behavior depends on the client and its connection model.
Start with a read-only test, constrain the target scope, and grant write access only for a defined task. Teams reviewing their Workspace structure and controls can also consider a ClickUp audit.
