https://github.com/juliandickie/clickup-plugin
Talk to ClickUp from Claude Code - token-disciplined task access and first-class, audited bulk operations.
https://github.com/juliandickie/clickup-plugin
claude-code clickup mcp model-context-protocol productivity project-management task-management
Last synced: 2 days ago
JSON representation
Talk to ClickUp from Claude Code - token-disciplined task access and first-class, audited bulk operations.
- Host: GitHub
- URL: https://github.com/juliandickie/clickup-plugin
- Owner: juliandickie
- Created: 2026-05-17T11:58:17.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-06-02T06:23:14.000Z (22 days ago)
- Last Synced: 2026-06-02T08:18:24.602Z (22 days ago)
- Topics: claude-code, clickup, mcp, model-context-protocol, productivity, project-management, task-management
- Language: Shell
- Homepage: https://promarketing.co
- Size: 1.37 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
Awesome Lists containing this project
README
Talk to ClickUp from Claude Code with token-disciplined task access and first-class, audited bulk operations.
# ClickUp for Claude Code
You run real work in ClickUp, and you drive Claude Code from the terminal. The two should talk to each other. The stock ClickUp connector makes that expensive and nerve-wracking on a real workspace, in two specific ways.
First, it is wasteful. It inlines the full custom-field option schema (`type_config`) on every single task it returns. On a list with dozens of options across hundreds of tasks, that is tens of thousands of redundant tokens on a single pull, before you have asked a single question.
Second, it is not safe to scale. There is no real bulk surface, so a mass change is either a hundred careful single calls or a leap of faith. And the moment a tool can touch a hundred tasks at once, the fear is rational. One bad call could reassign a sprint or delete a quarter of a board, and you would have no record of what happened.
A tool you are afraid to run at scale is not really a tool. This plugin was built for exactly that tension. It strips the schema bloat by default, and it puts a hard, explicit confirmation in front of every write, with a capped bulk path, a dry-run kill switch, and a local audit log of every mutation. You get ClickUp control from Claude Code that is fast, cheap, and auditable enough to actually trust.
The plan is three steps - add the marketplace, install the plugin, paste your own ClickUp token. Then ask Claude to list a workspace and you are working.
Works with any ClickUp workspace. You supply your own personal token, and every person who uses the plugin supplies their own.
## Install
Standalone, just this plugin.
```
/plugin marketplace add juliandickie/clickup-plugin
/plugin install clickup@clickup
```
Or, if you use the aggregate outfit catalog, the plugin is also listed there and installs the same way with `clickup@outfit`.
## Authentication
You need a ClickUp personal API token. Create one in ClickUp at Settings - Apps - Generate API Token. It starts with `pk_`. The plugin uses it read-write against your own account, so it can do anything you can do in the ClickUp UI.
Supply the token in any one of these ways. The plugin resolves them in this order.
1. The plugin config prompt - on install Claude Code asks for your ClickUp API token and stores it as a sensitive plugin setting.
2. The `CLICKUP_API_TOKEN` environment variable - set it to the `pk_` token directly, or to a 1Password secret reference like `op://Vault/ClickUp/credential` (requires the `op` CLI installed and signed in).
3. A machine-global file at `~/.config/clickup-plugin/config.toml` containing:
```toml
api_token = "pk_your_token_here"
```
The token is never written to any repository, never logged, and never sent anywhere except `api.clickup.com`.
## Token discipline - the core difference
ClickUp returns every custom field's full option list (`type_config`) on every task. On a list with dozens of options across hundreds of tasks that is tens of thousands of redundant tokens per pull. `list_tasks` and `get_task` strip `type_config` by default. When you genuinely need the option catalogue, call `list_custom_fields` once for the list, or pass `include_field_schema: true` on a specific call. This is the single biggest reason to use this plugin over the stock connector.
## Safety model
Every write is gated. The write tools refuse to run unless invoked through a `/clickup-*` command that has shown you a confirmation summary and received an explicit yes. There is no path to a silent write.
- Bulk operations via the MCP tool are recommended for up to 10 tasks. Sets larger than 10 use the bundled clickup-batch runner. The MCP tool still hard-refuses more than 100 as a safety backstop.
- A bulk delete needs a second explicit confirmation in addition to the normal one. A 100-task delete cannot happen by accident.
- Set `CLICKUP_DRY_RUN=1` to block all writes globally. In dry-run, write tools return a clearly labelled synthetic response and never touch ClickUp. Reads still work.
- Every mutating call is appended to a local audit log at `~/.local/share/clickup-plugin/audit.log` with a timestamp, the operator, the operation, your confirmation summary, and the affected ids. The audit write is best-effort and never aborts your operation.
## What you get
Skills (these activate on their own when relevant).
- `clickup-task-search` - find and summarise tasks in a list or space.
- `clickup-list-audit` - a canonical snapshot of a list - counts by status, custom-field coverage, relationship density.
- `clickup-bulk-plan` - plan a bulk change and preview it. This skill only ever plans. It never writes.
Commands (explicit, confirmed writes).
- `/clickup-task` - create or update a single task, after showing you a confirmation summary and waiting for your yes.
- `/clickup-bulk-apply` - apply a previously previewed bulk change to up to 10 tasks, after explicit confirmation. Larger sets use the bundled clickup-batch runner. Bulk deletes require a second, separate confirmation.
MCP tools (Claude calls these as needed, with the safety rules above).
- Navigation - `list_workspaces`, `list_spaces`, `list_folders`, `list_lists`, `get_list`.
- Read - `list_tasks` (auto-paginated, schema-stripped by default), `get_task`, `list_custom_fields`.
- Single writes (gated) - `create_task`, `update_task`, `delete_task`, `set_custom_field`, `add_comment`, `set_task_relationship`.
- Bulk (gated, capped) - `bulk_update_tasks`.
## Bulk and large jobs
`bulk_update_tasks` is recommended for sets of up to 10 tasks. For larger sets, or any job you want to run idempotently with a dry-run preview and a written report, use the `clickup-batch` runner. It ships with this plugin (installed as `clickup-batch` on PATH). It is dry-run by default, replaces a marker block in place so re-runs do not duplicate, and paces writes under ClickUp's rate limit. The MCP bulk tool hard-refuses more than 100 tasks as a safety backstop, but the recommended path for more than 10 tasks is the runner.
## The audit log
Every mutating call appends one line to `~/.local/share/clickup-plugin/audit.log` - timestamp, operator, operation, your confirmation summary, and the affected task ids. It is local only and never uploaded. The audit write is best-effort. If it fails (a read-only disk, for example) it logs to stderr and your operation still completes. The log is the answer to "what did this actually change", and it is yours alone.
## Requirements
- Node 18 or newer (the bundled MCP server runs on it).
- A ClickUp personal token (`pk_`).
## Optional configuration
- `CLICKUP_BASE_URL` - override the API base (defaults to `https://api.clickup.com/api/v2`). An unresolved `${...}` value is ignored and the default is used.
- `CLICKUP_DRY_RUN` - set to `1` to block all writes.
## Notes
This repository is generated. It is the lean, installable payload built and published from a separate development monorepo. Do not send pull requests here - see CONTRIBUTING.md. Day-to-day usage, examples, and troubleshooting are in USAGE.md.
## License
MIT.