Connect ClickUp to Claude: Sync Project Goals and Time Tracking

If you need to connect ClickUp to Claude to automate project management, time tracking, or goal alignment, 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 spend weeks building and maintaining 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 connecting ClickUp to AI Agents.

Giving a Large Language Model (LLM) read and write access to a sprawling work management ecosystem like ClickUp is a massive engineering challenge. You have to handle OAuth 2.0 token lifecycles, map incredibly dense JSON schemas to MCP tool definitions, and deal with ClickUp's strictly enforced hierarchy constraints. Every time an endpoint changes or you need to add a new tool for Docs or Goals, you have to update your server code, redeploy, and re-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 project management 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, the reality of implementing it against ClickUp's APIs is painful. ClickUp is not a flat list of tasks - it is a complex relational database mapped to a REST API.

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:

Deeply Nested Resource Hierarchies ClickUp enforces a strict organizational hierarchy: Workspace (Team) > Space > Folder > List > Task > Subtask. To create a task via the API, the LLM cannot simply say "create a task in the Engineering project." It must know the exact list_id. Finding that list_id requires querying the Workspace for Spaces, querying the Space for Folders, and querying the Folder for Lists. A custom MCP server must expose all of these traversal endpoints clearly, or the LLM will hallucinate IDs and fail. Truto auto-generates these traversal tools dynamically from its API documentation layer.

Custom Task IDs and Team Context ClickUp supports standard alphanumeric IDs and human-readable Custom Task IDs (like ENG-123). If you want the LLM to update a task using ENG-123, the API request must include the team_id parameter and set custom_task_ids=true. Managing this conditional logic across dozens of endpoints in a custom MCP server is tedious and error-prone.

Strict Data Formats and Quirks ClickUp APIs require specific, sometimes unintuitive data formats. For example, when interacting with the Time Tracking API, creating a running timer requires passing a negative duration value. If the LLM does not explicitly know this rule, it will fail to start timers correctly. Truto's dynamic tool generation uses enhanced schema descriptions to explicitly instruct the LLM on these vendor-specific quirks.

Rate Limits and 429 Handling ClickUp enforces rate limits per Workspace (typically 100 requests per minute per token). LLMs are aggressive - an AI agent traversing a Folder hierarchy to find a specific task can easily blow through this quota in seconds. It is critical to understand that Truto does not retry, throttle, or apply backoff on rate limit errors. When the ClickUp API returns an HTTP 429, Truto passes that error directly to the caller. Truto normalizes upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. The caller (the AI agent framework) is entirely responsible for reading these headers and implementing its own retry and backoff logic.

Instead of building all this boilerplate from scratch, you can use Truto. Truto normalizes authentication and schema generation, exposing ClickUp's hierarchical endpoints as ready-to-use MCP tools over a secure JSON-RPC 2.0 connection.

How to Generate a ClickUp MCP Server with Truto

Truto dynamically generates MCP tools from ClickUp's resource definitions and API documentation records. Tools are only exposed if they have an underlying documentation record, acting as a quality gate to ensure the LLM only sees well-described endpoints with accurate schemas.

Each MCP server is scoped to a single integrated account (your connected ClickUp instance). You can generate the server URL via the Truto UI or programmatically via the API.

Method 1: Creating the MCP Server via the Truto UI

For ad-hoc agent setups and internal tooling, you can generate an MCP server directly from the Truto dashboard:

1. Navigate to the Integrated Accounts page in your Truto environment.
2. Select your connected ClickUp account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration (name, allowed methods, tags, and optional expiration date).
6. Click Save and copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4e5f6...).

This URL contains a secure, hashed token that authenticates the connection. It is fully self-contained and ready to use.

Method 2: Creating the MCP Server via the API

For production workflows, you will want to generate MCP servers programmatically for your end users. The Truto API validates that the integration has tools available, provisions the secure token in edge key-value storage, and returns the endpoint.

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

curl -X POST https://api.truto.one/integrated-account/<clickup_account_id>/mcp \
  -H "Authorization: Bearer <YOUR_TRUTO_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ClickUp Engineering Workspace Sync",
    "config": {
      "methods": ["read", "write"],
      "tags": ["tasks", "time_tracking", "goals"]
    }
  }'

Response:

{
  "id": "mcp-789-xyz",
  "name": "ClickUp Engineering Workspace Sync",
  "config": {
    "methods": ["read", "write"],
    "tags": ["tasks", "time_tracking", "goals"]
  },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890"
}

Store this url. Your AI framework will use it to discover tools and execute JSON-RPC 2.0 payloads.

How to Connect the ClickUp MCP Server to Claude

Once you have your Truto MCP Server URL, connecting it to Claude takes less than a minute. You can do this via the Claude interface or by modifying the desktop configuration file.

Method 1: Via the Claude UI

Anthropic and OpenAI are standardizing interface-driven custom connectors.

1. Open Claude Desktop or the Claude Web Interface.
2. Navigate to Settings -> Integrations -> Add MCP Server (or Settings -> Connectors -> Add depending on your plan tier).
3. Name the connector "ClickUp (Truto)".
4. Paste the Truto MCP URL into the endpoint field.
5. Click Add.

Claude will immediately send an initialize request to the server, followed by a tools/list request. Truto will dynamically build and return the list of ClickUp tools, and Claude will surface them to your agent.

Method 2: Via the Manual Config File

If you are using Claude Desktop for local development or agent testing, you can add the server via the claude_desktop_config.json file. Because Truto MCP servers are remote HTTP endpoints, you use the standard Server-Sent Events (SSE) client wrapper.

Update your config file (typically located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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

Restart Claude Desktop. The icon in the prompt bar will indicate that the ClickUp tools are now available in context.

ClickUp Hero Tools for Claude

When Claude connects to the Truto MCP server, it receives a flat array of highly descriptive tools. The Truto documentation engine automatically translates ClickUp's complex payload requirements into clear JSON Schemas with semantic instructions.

Here are the most critical "hero tools" for ClickUp orchestration.

1. list_all_click_up_spaces

Before an LLM can create a task or folder, it must understand the environment. This tool fetches all Spaces for a workspace in ClickUp using team_id. It returns the ID, name, statuses, features, and custom fields available in that space.

"Find the Space ID for our 'Engineering Pipeline' workspace. I need to know what custom task statuses are configured for that space before we proceed."

2. list_all_click_up_tasks

This tool retrieves tasks filtered by a specific List ID. It returns a massive array of metadata, including assignees, standard fields, custom fields, time estimates, and current status.

"Get all tasks in the Sprint 42 list. Filter the response in your memory to only show tasks assigned to me that are in the 'In Progress' state."

3. create_a_click_up_task

This is the core write operation. It creates a new task under a specific list_id. The LLM can pass the name, description, priority, assignees, and start/due dates in a single payload.

"Create a new task in the Q3 Roadmap list called 'Migrate Auth Service'. Assign it high priority, add a description about moving to standard OAuth 2.0, and set the due date for next Friday."

4. create_a_click_up_time_entry

This tool allows the LLM to log time against specific tasks. It requires start, duration, assignee, and the tid (Task ID). Crucially, the Truto schema handles the ClickUp quirk where a negative duration indicates a running timer.

"Log 2 hours of time for me against the 'Migrate Auth Service' task. Add a description noting that I finished the token refresh logic."

5. list_all_click_up_goals

ClickUp Goals sit outside the standard Task hierarchy. This tool fetches Goals for a specific team_id, returning the goal name, owner, key result count, and overall percent completed.

"Pull our current Q3 Engineering Goals. Tell me which goal has the lowest completion percentage right now."

6. create_a_click_up_docs_page

ClickUp Docs are frequently used for RFCs, sprint planning, and architecture specs. This tool creates a new page inside a specific Doc using the workspace_id and doc_id.

"Create a new page in our Engineering Wiki doc called 'API Rate Limit Handling Plan'. Draft a summary of standard IETF headers and save it to the page."

This is just a subset of the available operations. For a complete list of endpoints, schemas, and required parameters, review the complete inventory on the Truto ClickUp integration page.

Workflows in Action

Giving Claude access to these tools turns it from a passive chat interface into an active project manager. By combining search, read, and write operations, the agent can execute multi-step workflows across the ClickUp hierarchy.

Scenario 1: Sprint Planning & Task Assignment

Product managers spend hours parsing raw feature requests and turning them into structured tickets. An AI agent can automate this entirely.

"Look at the attached CSV of user feedback. For every item mentioning 'SSO login errors', create a task in the 'Bug Triage' list. Group similar reports into the same task description, assign them to the backend team lead, and tag them with 'auth'."

Step-by-step execution:

1. Claude parses the uploaded CSV file locally.
2. Claude calls list_all_click_up_spaces and list_all_click_up_lists to resolve the string "Bug Triage" into a concrete list_id.
3. Claude aggregates the feedback data internally.
4. Claude calls create_a_click_up_task in a loop (or parallelized depending on agent config) to generate the tickets, passing the aggregated context into the description field.
5. Claude confirms the creation of the tickets and returns a summary table with the new Task IDs.

Scenario 2: End-of-Week Time Audit and Goal Sync

Engineers frequently forget to log hours or update OKR progress. An agent can read system data and execute the updates.

"Check all tasks assigned to me that were moved to 'Done' this week. Log 4 hours of time for each one. Then, update the 'Q3 Platform Stability' Goal key result to reflect these closed tickets."

Step-by-step execution:

1. Claude calls list_all_click_up_tasks with filters applied to find tasks assigned to the user with status: closed and updated within the last 7 days.
2. For each task returned, Claude calls create_a_click_up_time_entry, passing the tid, a duration of 14400000 milliseconds (4 hours), and a generated description.
3. Claude calls list_all_click_up_goals to locate the ID for the "Q3 Platform Stability" goal.
4. Claude calls update_a_click_up_goals_key_result_by_id to increment the metric.
5. Claude replies with a natural language confirmation that the time has been logged and the goal has been updated.

Security and Access Control

Handing an LLM unrestricted access to your company's ClickUp Workspace is a major security risk. You do not want a hallucinating model to delete a production roadmap or alter executive goals. Truto MCP servers provide strict, granular access controls at the server level.

• Method Filtering: You can enforce Read-Only access by passing "methods": ["read"] during server creation. Truto will strip all create, update, and delete operations from the generated tool list, ensuring the model can only query data, never mutate it.
• Tag Filtering: Limit the scope of the server to specific domains. By setting "tags": ["time_tracking", "goals"], the server will only expose endpoints related to those domains, completely hiding the core Task or Doc APIs from the LLM.
• Expiration Controls: Use the expires_at property to generate short-lived MCP servers. If you are building a temporary workflow for a contractor, set the server to expire in 7 days. Truto utilizes managed alarm schedulers and edge key-value storage expirations to ensure the token is permanently destroyed precisely on time.
• Secondary Authentication: By default, the MCP token URL is sufficient to connect. For zero-trust environments, enable require_api_token_auth. This forces the client to pass a valid user session or API Bearer token in the headers alongside the MCP URL, ensuring the caller is actually an authenticated member of your team.

Automate the Busywork

Connecting ClickUp to Claude fundamentally changes how your team interacts with project management software. Instead of clicking through six layers of folders to update a status or start a timer, engineers and PMs can execute complex operations through natural language.

Building a custom integration layer requires managing OAuth flows, writing endless JSON schemas, and babysitting rate limits. With Truto, you can generate a fully functional, highly secure MCP server for ClickUp in seconds. Pass the URL to Claude, and let the agent handle the orchestration.