Connect ClickUp to Claude: Track Goals, Docs, and Key Results

If you need to connect ClickUp to Claude to automate task management, track enterprise OKRs, or sync engineering documentation, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool calls and ClickUp's REST APIs. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses ChatGPT, check out our guide on connecting ClickUp to ChatGPT or explore our broader architectural overview on what an MCP server is.

Giving a Large Language Model (LLM) read and write access to a sprawling project management ecosystem like ClickUp is an engineering challenge. You have to handle OAuth 2.0 token lifecycles, map massive JSON schemas to MCP tool definitions, and navigate ClickUp's famously deep organizational hierarchy. Every time ClickUp updates an endpoint or changes how custom fields are handled, you have to update your server code, redeploy, and test the integration. This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for ClickUp, connect it natively to Claude, and execute complex workflows using natural language.

The Engineering Reality of the ClickUp API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools over JSON-RPC, the reality of implementing it against vendor APIs is painful. You are not just integrating "ClickUp" - you are integrating an API that attempts to be the "everything app" for work, which means dealing with extreme flexibility and nested data models.

If you decide to build a custom MCP server for ClickUp, you own the entire API lifecycle. Here are the specific challenges you will face:

The Six-Level Data Hierarchy ClickUp's data model is aggressively nested. A task does not just exist in a vacuum. A Task belongs to a List, which might belong to a Folder, which belongs to a Space, which belongs to a Team (Workspace). To execute a simple prompt like "Find my open tasks in the Engineering space," an LLM must navigate this hierarchy programmatically. If you dump raw endpoints into an LLM's context, the model will struggle to chain the required IDs together. A managed MCP server provides clear, normalized descriptions that teach the LLM exactly how to traverse Team -> Space -> Folder -> List -> Task.

Time Tracking Quirks and Negative Durations ClickUp handles active time tracking in a unique way. When a user starts a timer on a task, the API creates a time entry with a negative duration value. Only when the timer is stopped does the duration become positive. If you expose the raw time tracking API to Claude without explicit schema descriptions, the model will hallucinate invalid integers or fail to understand why an employee seemingly worked for -3600 seconds. Truto's generated schemas explicitly map these constraints so the LLM behaves correctly.

Strict Rate Limits and Header Propagation ClickUp enforces strict API quotas. Depending on your tier, you might be capped at 100 requests per minute per token. If your AI agent gets stuck in a loop or tries to summarize hundreds of tasks across multiple lists, ClickUp will return an HTTP 429 Too Many Requests error.

It is a factual note on how Truto operates: Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream ClickUp API returns a 429, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) following the IETF spec. Your AI agent framework or MCP client is responsible for reading these headers and implementing appropriate retry and exponential backoff logic.

Instead of building all this boilerplate from scratch, you can use Truto. Truto normalizes authentication and pagination, exposing ClickUp's endpoints as ready-to-use MCP tools.

How to Generate a ClickUp MCP Server with Truto

Truto dynamically derives tool definitions from the connected ClickUp account. Rather than hand-coding endpoints, Truto reads the integration's resource schema and active documentation to generate tools on the fly. This ensures that only curated, well-documented endpoints are exposed to your AI agents.

You can generate an MCP server URL in two ways: through the Truto UI or programmatically via the API.

Method 1: Via the Truto UI

This is the fastest method for internal testing or equipping your own local instance of Claude Desktop with ClickUp access.

1. Log in to your Truto dashboard and navigate to the integrated account page for your ClickUp connection.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Configure your server settings. You can name the server, restrict it to specific operations (like read only), or filter it by specific tags.
5. Click Create and copy the generated MCP server URL (it will look like https://api.truto.one/mcp/a1b2c3d4...).

Method 2: Via the API

For production workflows, such as spinning up temporary MCP servers for enterprise customers in your multi-tenant SaaS application, you should generate the server programmatically.

Make a POST request to the /integrated-account/:id/mcp endpoint:

const response = await fetch('https://api.truto.one/integrated-account/<clickup-account-id>/mcp', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <YOUR_TRUTO_API_TOKEN>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "ClickUp Engineering Workspace",
    config: {
      methods: ["read", "write"],
      tags: ["tasks", "spaces", "docs"]
    },
    expires_at: "2026-12-31T23:59:59Z"
  })
});
 
const mcpServer = await response.json();
console.log(mcpServer.url); 
// Output: https://api.truto.one/mcp/abc123def456...

The API validates that the integration has tools available, generates a secure cryptographic token, and returns a ready-to-use URL. Because the URL contains a cryptographic token linked directly to that specific integrated account, it is fully self-contained. No additional OAuth handshakes are required by the client.

How to Connect the MCP Server to Claude

Once you have the Truto MCP server URL, you need to register it with your Claude environment. Truto's MCP servers communicate using standard JSON-RPC 2.0 over HTTP POST (via Server-Sent Events or direct endpoints), making them natively compatible with Anthropic's ecosystem.

Method A: Via the Claude UI

If you are using an interface that supports dynamic connector registration (like the Claude web interface for Team/Enterprise plans, or ChatGPT's developer mode):

1. In your LLM interface, navigate to Settings -> Integrations -> Add MCP Server (or Settings -> Connectors -> Add custom connector depending on the specific UI layout).
2. Name your connection (e.g., "ClickUp via Truto").
3. Paste the Truto MCP server URL you generated in the previous step.
4. Click Add or Save. The LLM will immediately hit the initialize and tools/list endpoints to discover what actions it can take in ClickUp.

Method B: Via Manual Config File (Claude Desktop)

For local development using Claude Desktop, you register the MCP server by modifying your claude_desktop_config.json file. Because Truto provides a remote HTTPS endpoint, you use the standard @modelcontextprotocol/server-sse transport proxy to connect.

Locate your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the Truto MCP server under the mcpServers key:

{
  "mcpServers": {
    "clickup-truto": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/YOUR_TRUTO_TOKEN_HERE"
      ]
    }
  }
}

Save the file and restart Claude Desktop. The application will detect the new configuration, proxy the SSE connection to Truto, and populate Claude's context with your ClickUp tools.

ClickUp Hero Tools for Claude

Truto automatically generates highly descriptive snake_case tool names based on the ClickUp integration resources. When Claude requests the available tools, it receives the exact JSON schemas required to format API calls correctly.

Here are the most powerful hero tools your AI agents will use to orchestrate ClickUp workflows.

list_all_click_up_spaces

This tool is the required entry point for navigating a ClickUp environment. Because ClickUp requires space IDs to find folders, and folder IDs to find lists, an LLM must use this tool to discover the structural map of the workspace.

"I need to find the 'Q3 Marketing Launch' tasks. First, list all the ClickUp spaces in this account so we can find the right Space ID."

list_all_click_up_lists

Once the LLM has a Space or Folder ID, it uses this tool to retrieve the specific Lists where tasks actually live. It returns deep metadata about each list, including active statuses, priority colors, and task counts.

"Look up all the lists inside the 'Product Engineering' space. Find the list dedicated to 'Database Migrations' and tell me how many open tasks are in it."

list_all_click_up_tasks

This is the core retrieval tool for work items. It fetches filtered tasks from a specific list, returning the task name, description, assigned users, statuses, and custom fields. Truto automatically injects pagination instructions so the LLM knows exactly how to pass the next_cursor back to fetch subsequent pages.

"Fetch all tasks from the 'Sprint 42' list. Summarize the descriptions of any tasks currently marked as 'In Progress' or 'Blocked'."

create_a_click_up_task

Allows the agent to write data back to ClickUp. It accepts standard fields (name, description, status) as well as complex assignments. Truto's schema generation parses the required body payload, ensuring the LLM structures the JSON exactly as ClickUp demands.

"Create a new high-priority task in the 'Bug Backlog' list called 'Memory Leak in Auth Service'. Assign it to the backend team and add a description of the error logs I just provided."

get_single_click_up_goal_by_id

ClickUp Goals are often used for OKR tracking. This tool retrieves a specific goal, returning the current percentage completed, the owners, and the history of progress updates.

"Check the status of our 'Q4 Revenue Target' goal. Tell me the current completion percentage and who the primary owner is."

list_all_click_up_search_docs

ClickUp is not just for tasks; it includes a robust Docs feature. This tool allows the AI agent to search through the workspace's documentation to find relevant wikis, PRDs, or engineering guidelines to use as context.

"Search our ClickUp Docs for any pages mentioning 'API Rate Limiting Guidelines' and summarize the findings for me."

create_a_click_up_time_entry

Enables the agent to log time spent on a task. Because of ClickUp's unique negative-duration handling for running timers, the tool schema explicitly defines how the duration integer should be constructed, preventing LLM math hallucinations.

"Log 2 hours of billable time against the 'Refactor Login Component' task. Add a description that says 'Updated OAuth flows and tested edge cases'."

For a full list of all supported endpoints, custom schemas, and data types, visit the ClickUp integration page.

Workflows in Action

Exposing individual endpoints to an LLM is only half the battle. The real power of an MCP server is enabling the AI agent to orchestrate multi-step, autonomous workflows that traverse the API. Here is how Claude uses these tools in the real world.

Scenario 1: Automated Sprint Triage

Persona: Engineering Manager

"Review all the unassigned tasks in the 'Incoming Bugs' list. Based on the task descriptions, assign any frontend issues to Sarah and any backend issues to David. Then, summarize what was assigned to whom."

Step-by-step execution:

1. Claude calls list_all_click_up_lists to verify the ID of the 'Incoming Bugs' list.
2. Claude calls list_all_click_up_tasks using that list ID, extracting the names, descriptions, and current assignees of all open issues.
3. The LLM reads the descriptions, using its internal logic to classify them as frontend or backend.
4. Claude makes multiple parallel calls to update_a_click_up_task_by_id, modifying the assignees array for each task based on the classification.
5. The model outputs a clean, markdown-formatted summary to the user detailing exactly which tasks were triaged.

Scenario 2: OKR Progress Syncing

Persona: Director of Operations

"Look up our 'Reduce Churn' Goal in ClickUp. Check the related Key Results and cross-reference them with the tasks in the 'Customer Success Q3' list. Are there any high-priority tasks that are blocked that might prevent us from hitting this goal?"

Step-by-step execution:

1. Claude calls get_single_click_up_goal_by_id to retrieve the 'Reduce Churn' goal and its associated Key Results.
2. Claude calls list_all_click_up_tasks for the 'Customer Success Q3' list.
3. The agent filters the tasks in memory, specifically looking for tasks with priority set to high and status set to 'Blocked' or 'Stuck'.
4. The LLM analyzes the correlation between the blocked tasks and the Key Results, generating a strategic report on operational risk without the Director having to manually click through five different ClickUp dashboards.

Security and Access Control

Giving an AI agent access to an enterprise ClickUp workspace requires strict security boundaries. If an agent hallucinates a delete command, the consequences could be severe. Truto provides granular controls at the MCP token level to prevent this:

• Method Filtering: You can restrict a Truto MCP server to specific HTTP methods. By setting config.methods: ["read"] during token creation, you guarantee the LLM can only execute get and list operations, physically preventing it from creating, updating, or deleting tasks.
• Tag Filtering: You can restrict the server to only expose tools associated with specific tags. For example, setting tags: ["docs"] ensures the agent can read and write ClickUp documentation, but has zero visibility into tasks, goals, or time tracking.
• Secondary Authentication (require_api_token_auth): By default, possessing the MCP URL is enough to connect. For high-security environments, setting require_api_token_auth: true forces the client to also pass a valid Truto API token in the Authorization header. This prevents unauthorized users from using the MCP URL even if it leaks in a local configuration file.
• Automatic Expiry (expires_at): You can bind a strict Time-To-Live (TTL) to the MCP server. Once the expires_at timestamp is reached, Truto automatically deletes the underlying cryptographic token and scheduled alarms purge it from distributed storage. Subsequent tool calls will immediately fail with an authentication error.

Moving Past Bespoke Integration Scripts

Connecting ClickUp to Claude should not require a dedicated engineering team writing custom JSON-RPC handlers, maintaining pagination cursors, or debugging undocumented API quirks. The AI integration landscape has shifted from bespoke scripts to standardized protocol layers.

By leveraging Truto's dynamic tool generation, you transform ClickUp's sprawling data hierarchy into a clean, predictable set of capabilities that Claude can immediately understand and orchestrate. You avoid the maintenance burden of tracking API deprecations, and you give your AI agents the secure, structured access they need to actually accomplish real work.