Install and connect in two actions.#
Choose ClickUp and GitHub independently#
Default: hosted ClickUp + GitHub CLI. Use official ClickUp MCP with browser-based OAuth and reuse gh sign-in across authorized GitHub repositories. No ClickUp desktop app, ClickUp CLI, personal ClickUp token, local helper or bridge is required. The installer checks GitHub sign-in; only the running agent can verify ClickUp OAuth and actual repository access.
Use onboard --mode hosted --github cli explicitly for this combination. --mode hosted --github hosted instead selects an existing approved hosted GitHub connection. Strict remote-only (--mode remote-only, legacy --mode oauth) requires both connections to be hosted and never invokes gh. Missing or banned selected backends mean STOP; do not automatically fall back.
Local-helper (--mode local-helper, legacy --mode cli) separately installs cup/cu-work and requires its own ClickUp token. Existing setup/update keep their local-helper semantics. Hosted operations use agent-instruction safeguards, outside helper receipts, locks and completion gates.
The convenience installer runs Node 22+, Python 3.11+ and Git; the default also needs an already allowed GitHub CLI. The strict manual route can use existing hosts with no extra local tools. See modes and host constraints.
Choose the coding agent you actually use, not merely the editor where it runs. The default ClickUp authentication method is browser-based OAuth. Each teammate must configure their own agent environment and authorize their own accounts.
1. Run one command in your terminal#
Install Node.js 22+, Python 3.11+, Git, and GitHub CLI (gh) first for the default backend. The same command works in macOS Terminal and Windows PowerShell:
npx --yes github:randrescastaneda/clickup-skills onboard
The command installs from main, the repository's default branch. The installer asks which agent to configure. Press Enter for Kilo Code (default). If you already know the agent, append the appropriate --client option:
| Agent you actually run | Terminal command / option |
|---|---|
| Kilo Code, including its VS Code extension | onboard --client kilo |
| Codex CLI or Codex extension | onboard --client codex |
| Claude Code | onboard --client claude |
| GitHub Copilot CLI | onboard --client copilot |
| GitHub Copilot Chat inside VS Code, Agent mode | onboard --client vscode --project-dir /absolute/path/to/project |
For every row, the full command begins with npx --yes github:randrescastaneda/clickup-skills. Do not run all five. Choose only the agent you use. For a VS Code extension that is Kilo, Codex, or Claude Code, use that agent's option—not vscode. The working project must already exist when using --project-dir.
Detailed instructions for each agent, including which settings file changes, OAuth steps and verification commands.
What it does: Installs six agent skills, adds ClickUp's official remote MCP endpoint (https://mcp.clickup.com/mcp) to your agent configuration and verifies/reuses gh browser sign-in by default. No hosted GitHub MCP or manually created per-repository token is needed for that backend. Use --mode hosted --github hosted to select an existing hosted connection; strict --mode remote-only never invokes gh. Settings and existing server entries are preserved. Conflicting or locally edited skill copies are not overwritten.
What it does NOT do: It does not install Krodak's CLI, access a private ClickUp token, authenticate ClickUp in the terminal, or enable the local helper's durable journal. ClickUp OAuth happens inside your coding agent in Step 2, not through npx.
If the installer finds an existing equivalent ClickUp MCP server under a different name, it reuses it rather than installing a duplicate. An existing clickup_work server, if present, is preserved but is not authenticated by hosted OAuth.
2. Reload your agent and verify OAuth#
Restart or reload the selected coding agent and send this instruction in its chat:
Use the clickup-setup skill to verify my OAuth-based ClickUp Skills installation.
Discover the six skills and the official ClickUp MCP tools. Verify GitHub
access via the selected GitHub backend (gh by default); stop if unavailable.
Guide me through the official ClickUp MCP's browser OAuth flow only if needed.
Verify read-only access to my intended Workspace, List and task, plus my GitHub
repository. Do not create or modify any tasks, issues or PRs.
Report the authenticated servers, exact scope, and missing setup (if any).
Why is the second step needed? The terminal configures the server; only your running coding agent can complete hosted ClickUp OAuth and discover the tools and permissions. The default installer does not install GitHub MCP, avoiding duplicate or incompatible GitHub authentication. The default uses gh; --github hosted delegates GitHub verification to the agent. Missing selected tools stop the workflow without automatic fallback.
For client-specific verification: Kilo: Kilo Settings → Agent Behaviour → MCP Servers; Codex: codex mcp list and, if needed, codex mcp login clickup_official; Claude Code: /mcp; Copilot CLI: /mcp or copilot mcp list; VS Code Copilot Chat: open Agent mode and check available MCP servers/tools. The ClickUp connection must perform an actual authenticated read before you authorize writes. See each client's exact instructions.
With GitHub CLI selected, an older unchanged installer-owned GitHub remote in Kilo is disabled; user-owned entries are preserved. With hosted GitHub selected, existing remote entries are retained for actual authentication verification.
Already using the official ClickUp MCP?
Your existing browser OAuth session may continue to work. The installer reuses a legitimate configured endpoint without replacing your sign-in or forcing a fresh ClickUp token. Reload the agent, then ask it to verify which server was discovered.
What is included and what is not#
| Default hosted ClickUp + GitHub CLI | Full local helper mode |
|---|---|
| No ClickUp API token. Official ClickUp MCP authorizes in the agent's browser flow | Requires the ClickUp CLI's personal API token, unless it is already configured |
Six skills + hosted ClickUp MCP + reusable gh sign-in |
Six skills + private Python workflow + Krodak CLI + local clickup_work MCP |
| Agents execute operations directly, following a guarded host issue-first protocol | Local helper enforces project scope and records durable operation receipts when a valid binding is configured |
| Markers and read-backs reduce duplicates; no local helper journal or cross-machine exactly-once guarantee | Helper journals and OS locks cover local writes, not other machines or direct host calls |
Both modes require task/repository access and a verified project scope. GitHub-first links, bounded writes, and safe retry rules are required in either mode. An authorized OAuth grant may be able to write even while you are testing reads: agents must respect the actual approved write scope.
Optional: install the full helper instead#
To enable the stricter local helper and its synchronization worker, choose --mode cli explicitly:
npx --yes github:randrescastaneda/clickup-skills onboard --mode cli --client kilo
This installs our Python workflow and Krodak's @krodak/clickup-cli@latest. If the user's personal ClickUp CLI sign-in has not been configured, the terminal guides them to ClickUp Settings → Apps to generate a token and enter it securely via cup init; cup auth verifies it. Existing valid CLI credentials are reused. This does not authorize the official hosted MCP. Keep tokens out of tasks, chats, commands, and version control.
The original software-only command remains supported and intentionally does not authenticate accounts:
npx --yes github:randrescastaneda/clickup-skills setup --client kilo
Who does what#
| Role | Responsibility |
|---|---|
| Workspace owner/admin | Grant access to ClickUp Workspaces/Lists and optionally configure the native GitHub integration/automations |
| Repository/organization admin | Give the right teammates and GitHub App access to the intended repositories |
| Each teammate | Run the installer and approve their own browser authorizations |
| Project lead + agent | Verify objective, GitHub owner/repo/base, ClickUp Workspace/List/root tasks and task permissions |
| Each agent + teammate | Confirm skill discovery, bounded writes and a small end-to-end pilot before production automation |
A teammate installing the plugin does not install it for the entire team. No credentials are shared through .clickup/project.json.
Bind your working project#
The project you are actually editing (not the ClickUp Skills repository) can contain .clickup/project.json binding its objective, repository, Workspace, home List, roots and statuses. The project setup explains it.
In OAuth mode, an agent can read an approved binding directly; it must verify the live identity/ancestry through the official MCP. An unbound agent must ask for explicit project scope before writing. It must not pretend that direct host calls use the local helper journal.
Small approved write pilot#
After read-only access is verified, choose a disposable or explicitly authorized task. Ask the agent to verify the GitHub issue or PR before creating a child, include the canonical issue/PR URL in the initial description, read it back via text_content, append exactly one managed GitHub backlink, and re-run the preflight expecting zero extra writes. The host agent follows the official-MCP guarded workflow; it stops on incomplete history or uncertain writes.
Do not mark a task Done simply because a PR exists. The linked merged non-draft PR, current checks, and acceptance evidence are separate gates.
Alternative and advanced installation#
Standard Vercel Skills CLI (manage skills separately)
The standard Vercel CLI installs skills but does not configure hosted MCPs or the local Python helper:
npx skills add randrescastaneda/clickup-skills -g
npx --yes github:randrescastaneda/clickup-skills onboard --client kilo --skip-skills
These two commands are an alternative to the single bundled installer, not an extra requirement. The --skip-skills option preserves Vercel-owned copies. For the local full-helper option append --mode cli to the second command. Use Vercel's skills check / skills update -g to maintain its copies. Avoid duplicate skill managers in the same directory.
Extra clients, project scope, and contributor setup
Use the per-agent guide for Codex, Claude Code, Copilot CLI, VS Code Copilot Chat, and Kilo verification steps. For project-specific configuration supply --project-dir /absolute/path/to/project; VS Code MCP uses --client vscode and requires that flag. The agent running in the editor owns tool discovery and its OAuth authorization. Preserve existing manual customizations; conflicts stop instead of overwriting files.
For OpenCode, Posit Assistant, and special/legacy clients, use the client setup matrix and manual scripts in the repository README.
Keep installations current#
For the default hosted installation, rerun the same onboarding command to refresh the hosted MCP configuration and any skills managed by the installer:
npx --yes github:randrescastaneda/clickup-skills onboard --client kilo
If you selected a different backend, keep the same mode and backend flags when you rerun onboard.
For an installed token-backed local helper, update keeps its previous full-runtime semantics:
npx --yes github:randrescastaneda/clickup-skills update --client kilo
The full helper explicitly updates its private runtime and Krodak's latest CLI. Do not update in the middle of a task write. Reload the client and verify discovery after updates. Website publication never updates local agent installations.
Optional native ClickUp–GitHub integration#
The plugin does not install a GitHub webhook, activate native ClickUp GitHub links, start a synchronizer, or create automation rules. Those are separate tasks requiring authorized administrators and possibly plan features. See native integration setup, ClickUp's integration guide, and GitHub Automations.