@me-team/clickup-gap-mcp

Companion MCP server for ClickUp gaps that are awkward or missing in the official ClickUp MCP:

• create/update tasks with explicit custom_item_id;
• create checklists and checklist items;
• optionally add dependencies with explicit blocked_by / blocks direction.

Requirements

• Node.js 20.11 or newer;
• a ClickUp personal API token.

Usage with MCP clients

Use the published npm package directly with npx:

{
  "mcpServers": {
    "clickup-gap-mcp": {
      "command": "npx",
      "args": ["-y", "@me-team/clickup-gap-mcp"],
      "env": {
        "CLICKUP_API_TOKEN": "your-clickup-api-token",
        "CLICKUP_TEAM_ID": "your-clickup-team-id"
      }
    }
  }
}

CLICKUP_TEAM_ID is optional for tools where team_id is provided explicitly.

MCP tool approvals are controlled by the client, not by this server. Disabling a client filesystem sandbox does not necessarily disable confirmations for tools that call external services or change ClickUp data. This server publishes MCP tool annotations so clients can distinguish read-only ClickUp lookups from write operations.

For Codex:

codex mcp add clickup-gap-mcp \
  --env CLICKUP_API_TOKEN="your-clickup-api-token" \
  --env CLICKUP_TEAM_ID="your-clickup-team-id" \
  -- npx -y @me-team/clickup-gap-mcp

Codex mcp add does not currently expose a dedicated flag for MCP tool approval mode. To let Codex use this server's tools without per-call approval prompts, add the approval policy to ~/.codex/config.toml after running codex mcp add:

[mcp_servers.clickup-gap-mcp]
default_tools_approval_mode = "approve"

To auto-approve only selected tools, keep the default as prompt and override individual tools:

[mcp_servers.clickup-gap-mcp]
default_tools_approval_mode = "prompt"

[mcp_servers.clickup-gap-mcp.tools.clickup_gap_get_task_types]
approval_mode = "approve"

[mcp_servers.clickup-gap-mcp.tools.clickup_gap_create_task_with_type]
approval_mode = "approve"

Codex also supports a one-off config override when starting a session:

codex -c 'mcp_servers.clickup-gap-mcp.default_tools_approval_mode="approve"'

Environment

CLICKUP_API_TOKEN=your-clickup-api-token
CLICKUP_TEAM_ID=your-clickup-team-id

Optional:

CLICKUP_API_BASE_URL=https://api.clickup.com/api/v2
CLICKUP_MCP_SKIP_DOTENV=1

When running locally, the server also reads a .env file from the current working directory unless CLICKUP_MCP_SKIP_DOTENV=1 is set.

Local development

Install dependencies:

npm install

Configure local env vars:

cp .env.sample .env

Build and run:

npm run build
npm start

Local MCP client config:

{
  "mcpServers": {
    "clickup-gap-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/clickup-mcp/dist/index.js"],
      "env": {
        "CLICKUP_API_TOKEN": "your-api-token",
        "CLICKUP_TEAM_ID": "your-team-id"
      }
    }
  }
}

Tools

• clickup_gap_get_task_types
• clickup_gap_create_task_with_type
• clickup_gap_update_task_type
• clickup_gap_create_checklist
• clickup_gap_add_checklist_items
• clickup_gap_create_task_checklist
• clickup_gap_update_checklist_item_resolved
• clickup_gap_check_checklist_item
• clickup_gap_uncheck_checklist_item
• clickup_gap_add_dependency