---
slug: "khmuhtadin-pi-clickup-mcp"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/khmuhtadin/pi-clickup-mcp@main/README.md"
repo: "https://github.com/khmuhtadin/pi-clickup-mcp"
source_file: "README.md"
branch: "main"
---
# pi ClickUp MCP Extension

A pi package that bridges pi to the official ClickUp remote MCP server (`https://mcp.clickup.com/mcp`).

It exposes a small, generic bridge instead of registering dozens of ClickUp tools by default. This keeps pi's tool list compact while still allowing the model to discover and call any ClickUp MCP tool.

## Installation

From npm, after publishing:

```bash
pi install npm:@khmuhtadin/pi-clickup-mcp
```

From git:

```bash
pi install git:github.com/<user>/<repo>
```

For local development:

```bash
pi install /absolute/path/to/pi-clickup-mcp-extension
```

## Registered tools

- `clickup_mcp_list_tools` — list tools exposed by the ClickUp MCP server.
- `clickup_mcp_call_tool` — call any ClickUp MCP tool by `name` with JSON `arguments`.

Example prompt after authorization:

```text
List ClickUp MCP tools, then search my workspace for tasks mentioning onboarding.
```

## Slash commands

- `/clickup-mcp-auth-url` — start OAuth and print the ClickUp authorization URL to the terminal.
- `/clickup-mcp-auth <full-redirect-url-or-code>` — finish OAuth with the full redirect URL or the `code` value from that URL.
- `/clickup-mcp-token-status` — show token status without exposing token values.
- `/clickup-mcp-reset` — clear stored OAuth credentials.
- `/clickup-mcp-register [tool1,tool2|*]` — optional: register selected MCP tools as native pi tools with a `clickup_` prefix.

## OAuth flow

1. Start or reload pi.
2. Run:

   ```text
   /clickup-mcp-auth-url
   ```

3. Open the printed ClickUp authorization URL in your browser.
4. After approval, the browser redirects to `http://localhost:9876/callback?...`. A local server is not required; copy the full redirect URL from the address bar.
5. Run:

   ```text
   /clickup-mcp-auth <full-redirect-url>
   ```

   You can also paste only the `code` query parameter value, but do not include `code=`, `&state=...`, or whitespace.

6. Test by asking pi to use `clickup_mcp_list_tools`.

Credentials are stored at:

```text
~/.pi/agent/extensions/clickup-mcp/auth-store.json
```

## Configuration

Optional environment variables:

- `CLICKUP_MCP_URL` — defaults to `https://mcp.clickup.com/mcp`.
- `CLICKUP_MCP_REDIRECT_URL` — defaults to `http://localhost:9876/callback`.
- `CLICKUP_MCP_STORE_PATH` — defaults to `~/.pi/agent/extensions/clickup-mcp/auth-store.json`.
- `CLICKUP_MCP_TIMEOUT_MS` — defaults to `10000`.
- `CLICKUP_MCP_SCOPE` — defaults to `read write`.

## Refresh token note

At the time this package was created, ClickUp MCP OAuth metadata advertised:

```json
"grant_types_supported": ["authorization_code"]
```

That means the server does not advertise `refresh_token` grant support. This package requests `read write` scope, but a refresh token can only exist if ClickUp's OAuth server returns one. If `/clickup-mcp-token-status` reports `refresh_token: missing`, that is a ClickUp MCP server limitation, not a pi extension limitation.

## Development

```bash
npm install
npm run typecheck
npm pack --dry-run
```

## License

MIT