Folder MCP API

Tools for creating, listing, retrieving, updating, and deleting folders.

Errors and retries

All MCP tools return a uniform ToolResponse envelope (ok, result, issues[]). When ok: false, inspect issues and apply retries/backoff (respect retry_after_ms for 429 and back off on 5xx/transient errors). See Errors and Retries (MCP) for details.

Tools

folder.list_in_space

Lists all folders within a given space (space_id). This is a read-only discovery call that returns the minimal folder metadata (e.g., { id, name }) so you can enumerate containers before working with lists and tasks inside them.

• Parameters: FolderListInSpaceInput

{
  "space_id": "space_1" // Space ID to list folders within
}

• Returns: FolderListResult in ToolResponse

{
  "ok": true, // Tool succeeded
  "result": {
    "items": [
      {
        "id": "folder_1", // Folder ID
        "name": "Planning" // Folder name
      }
    ]
  },
  "issues": [] // Optional warnings/issues collected during execution
}

• Errors
  • AUTH_ERROR (401), FORBIDDEN (403)
  • NOT_FOUND (404) when space_id is invalid
  • RATE_LIMIT (429)
  • UPSTREAM_ERROR (5xx/timeout)

folder.get

Retrieves a single folder by folder_id. Read-only. Useful to validate the folder exists and to read its core properties like name and parent space_id before performing updates.

• Parameters: FolderGetInput

{
  "folder_id": "folder_1" // Target folder ID
}

• Returns: FolderResult

{
  "id": "folder_1", // Folder ID
  "name": "Planning", // Folder name
  "space_id": "space_1" // Parent space ID
}

• Errors
  • AUTH_ERROR (401), FORBIDDEN (403)
  • NOT_FOUND (404) when folder_id does not exist
  • RATE_LIMIT (429)
  • UPSTREAM_ERROR (5xx/timeout)

folder.create

Creates a new folder under the specified space (space_id). This operation has side effects in ClickUp and returns the newly created folder on success. Ensure the token has permission to create folders in the target space.

• Parameters: FolderCreateInput

{
  "space_id": "space_1", // Parent space ID
  "name": "[TEST] Planning" // Folder name
}

• Returns: FolderResult

{
  "id": "folder_1", // New folder ID
  "name": "[TEST] Planning", // Folder name
  "space_id": "space_1" // Parent space ID
}

• Errors
  • AUTH_ERROR (401), FORBIDDEN (403)
  • NOT_FOUND (404) when space_id is invalid
  • RATE_LIMIT (429)
  • UPSTREAM_ERROR (5xx/timeout)

folder.update

Updates an existing folder. Provide only the fields you want to change (e.g., name). Returns the updated folder. Requires appropriate permissions in the target space.

• Parameters: FolderUpdateInput

{
  "folder_id": "folder_1", // Target folder ID
  "name": "Roadmap" // New folder name
}

• Returns: FolderResult

{
  "id": "folder_1",
  "name": "Roadmap",
  "space_id": "space_1"
}

• Errors
  • AUTH_ERROR (401), FORBIDDEN (403)
  • NOT_FOUND (404) when folder_id does not exist
  • RATE_LIMIT (429)
  • UPSTREAM_ERROR (5xx/timeout)

folder.delete

Permanently deletes a folder by folder_id. This is a destructive operation and cannot be undone. Consider workspace retention policies before deleting.

• Parameters: FolderDeleteInput

{
  "folder_id": "folder_1" // Target folder ID
}

• Returns: DeletionResult

{
  "deleted": true // True if the folder was deleted
}

• Errors
  • AUTH_ERROR (401), FORBIDDEN (403)
  • NOT_FOUND (404) when folder_id does not exist
  • RATE_LIMIT (429)
  • UPSTREAM_ERROR (5xx/timeout)