DevBoy tools

    ClickUp Integration

    DevBoy tools provides integration with ClickUp for managing tasks (issues) through AI assistants. ClickUp tasks are mapped to the unified issue interface, so you can work with them alongside GitHub and GitLab issues.

    Quick Config Generator

    Required token

    ClickUp uses a Personal API Token for authentication. You can generate one in ClickUp:

    Settings > Apps > API Token > Generate

    Token TypeDescriptionRequired For
    Personal API TokenFull access to your workspaceReading/creating tasks, comments
    Note

    ClickUp Personal API Tokens do not use the Bearer prefix — the token is sent directly in the Authorization header.

    Configuration

    Basic configuration

    # Required: list ID (found in the list URL)
devboy config set clickup.list_id <list_id>

# Recommended: team ID for custom task IDs (e.g., DEV-42)
devboy config set clickup.team_id <team_id>

# Store token in OS keychain
devboy config set-secret clickup.token <token>
    [Recommended: Set

    team_id] While team_id is optional, setting it significantly improves the integration:

    • Custom Task IDs — tasks are identified as DEV-42 instead of CU-86c88mv5
    • create_issue returns custom IDs — newly created tasks show their custom ID (e.g., DEV-542)
    • Lookup by custom ID — get_issue, update_issue, add_comment all accept custom IDs directly

    Without team_id, tasks are only accessible via internal ClickUp IDs (CU-{id} format).

    Configuration file

    Settings are stored in ~/.config/devboy-tools/config.toml:

    [clickup]
team_id = "9015891466"
list_id = "901234567890"

    The token is stored separately in the OS keychain for security.

    Finding your IDs

    Both team_id and list_id can be found in the ClickUp URL when viewing a list:

    https://app.clickup.com/9015891466/v/li/901234567890
                        ^^^^^^^^^^       ^^^^^^^^^^^^
                        team ID          list ID

https://app.clickup.com/9015891466/v/l/6-901234567890-1
                        ^^^^^^^^^^       ^^^^^^^^^^^^
                        team ID          list ID

    In the /v/l/ format, the list ID is the number between the hyphens.

    You can also find the list ID via List Settings > List Info > List ID.

    MCP tools

    Once configured, the following MCP tools are available:

    Issue tools (tasks)

    ToolDescription
    get_issuesList tasks with filters (state, tags, assignee, pagination)
    get_issueGet a single task by key (e.g., CU-abc123 or DEV-42)
    get_issue_commentsGet all comments for a task
    create_issueCreate a new task in the configured list
    update_issueUpdate an existing task (title, description, status, priority)
    add_issue_commentAdd a comment to a task

    Task key format

    • Default: CU-{task_id} (e.g., CU-abc123)
    • Custom ID: If your workspace has custom task IDs enabled and team_id is configured, the custom ID is used as the key (e.g., DEV-42)
    Note

    Custom task IDs (e.g., DEV-42) require team_id to be set in configuration. Without team_id, all tasks use the CU-{id} format.

    Priority mapping

    ClickUp priorities are mapped to the unified format:

    ClickUp PriorityUnified Priority
    1 - Urgenturgent
    2 - Highhigh
    3 - Normalnormal
    4 - Lowlow

    Merge request tools

    ClickUp does not have merge requests. All MR-related tools will return a ProviderUnsupported error when used with ClickUp. Use a GitHub or GitLab provider for MR operations.

    Output formats

    All tools support three output formats via the format parameter:

    • markdown (default) - Human-readable with formatting
    • compact - Condensed format for limited context
    • json - Raw JSON data

    Example:

    {
  "key": "CU-abc123",
  "format": "json"
}

    Testing

    Verify your ClickUp configuration:

    devboy test clickup

    This will test the connection by verifying the token can access the configured list.

    Troubleshooting

    "401 Unauthorized" error

    • Verify your API token is copied correctly
    • Check that the token hasn't been revoked
    • Ensure you're using a Personal API Token (not an OAuth token)

    "404 Not Found" error

    • Verify the list ID is correct
    • Ensure the list exists and is accessible with your token
    • Check that the task ID exists when using get_issue

    "403 Forbidden" error

    • Your token may not have access to the workspace or list
    • Check your workspace permissions in ClickUp

    Rate limiting

    ClickUp API has rate limits:

    • 100 requests per minute per token
    • The tool will show a rate limit error if exceeded