ClickUp Serviteur MCP

ClickUp Serviteur MCP

Self-hosted ClickUp integration for MCP clients · TypeScript · Cloudflare Workers · dual OAuth · MIT License

Release candidate: v0.3.0-beta.1 — public source beta (7 November 2026)

ClickUp Serviteur is a remote Model Context Protocol server exposing ClickUp REST operations to MCP-compatible AI clients, including ChatGPT and Claude clients that support remote MCP. Each installation is operated by its own administrator, uses a separate Cloudflare Worker, and verifies both MCP-client identity and the individual's ClickUp OAuth credentials. This is an independent community project, not a product of or affiliated with ClickUp.

Public source does not mean public access to a running Worker. The reference company deployment is a privately authorized installation. Do not connect strangers to that endpoint, copy another operator's Workspace IDs, or reuse any shared credentials.

Official MCP Registry: Self-hosted registry installation and publication guide. Each user must supply the HTTPS hostname of their own configured Worker; the listing does not provide a shared public ClickUp service.

Features

• Real ClickUp REST-backed tools for scoped task search, task creation, assignment and editing; lists, folders, tags, dependencies, task links, comments, Custom Fields, time entries, Docs and Chat where supported by the upstream REST API.
• Native task/List Markdown descriptions and Markdown readback; Docs and Chat have separate text/md and text/plain handling. Native structured rich task comments support emphasis, links, list/checklist/toggle formatting, code, emojis, and verified genuine @mentions.
• A bounded PDF reader for supported text-based attachments. Image/file-upload adapters and several less-common API paths still have open acceptance work; see Known limitations.
• Authenticated company-owner cleanup of an exact task, the owner's own comments, tags, links and dependencies, with explicit confirmation and scope validation. This is not unrestricted bulk deletion.
• OAuth-bound Workspace or List scope, individual user tokens, encryption at rest for stored credentials, API rate-limit handling, strict request validation and no blind retry after uncertain writes.
• Cloudflare Workers HTTPS hosting, GitHub Actions CI, CodeQL and manually invoked protected deployments.

What has actually been verified

In November 2026, a protected company deployment was checked against its exact GitHub build SHA. With an individually authorized ClickUp connection, we verified successful creation and assignment of a disposable task, native Markdown description storage, a rich comment with stored formatting segments, and exact task/comment readback. API readback alone is not proof of visual fidelity for every editor-only block. Not every endpoint or third-party MCP client has completed live acceptance.

Formatting compatibility matrix · Release notes · Project limitations · Security

Requirements

• Node.js 22.20.0 or newer and npm for development or GitHub Actions builds.
• A Cloudflare account with Workers, a dedicated OAuth KV namespace and the required SQLite Durable Objects.
• GitHub OAuth credentials to authenticate MCP users; ClickUp OAuth app credentials to authorize each person against their own ClickUp account.
• A specific ClickUp Workspace/List and individually authorized users. Configure your own IDs and OAuth clients; sample values are never production grants.
• An MCP client that can connect to an OAuth-protected remote server.

Run the checks

git clone https://github.com/cryogenized-spec/ClickUp-Serviteur-MCP.gitcd ClickUp-Serviteur-MCPnpm ci --ignore-scripts --no-audit --no-fundpython3 scripts/check_repo_policy.pypython3 -m unittest discover -s scripts/tests -p 'test_*.py' -vnpm run format:checknpm run lintnpm run typechecknpm testnpm run buildnode scripts/staging-local-smoke.mjsnpm audit --audit-level=high

The root package is intentionally private: true: this beta is open-source on GitHub, not a published npm package. Do not treat a green test suite as confirmation of configured cloud secrets or ClickUp authorization.

Deploy your own instance

The maintained deployment paths are staging and isolated company. They are invoked manually from reviewed main; they do not publish an unauthenticated ClickUp gateway.

1. Fork the source or create a repository you control. Configure two separate OAuth clients (GitHub for the MCP connection, ClickUp for the upstream personal account) and register the exact HTTPS redirect origins. Use different credentials and stores for staging and company environments.
2. Create Cloudflare OAuth KV and the Worker/Durable Object bindings. Store GITHUB_CLIENT_SECRET, CLICKUP_CLIENT_SECRET, CLICKUP_STATE_KEY and CLICKUP_TOKEN_KEY only as Cloudflare secrets or appropriate protected deployment secrets, never as Git-tracked files. Confirm the key encoding requirements in OAuth setup.
3. Configure repository staging environment variable STAGING_OAUTH_KV_ID and an explicit comma-separated allowlist STAGING_WORKSPACE_GITHUB_IDS containing only GitHub identities you authorize. The public beta no longer defaults to the original repository owner's GitHub ID.
4. Choose your own Worker hostname and configure its OAuth callbacks, public origin, ClickUp Workspace/List bindings and staff mapping. See Deployment and permissions and Workspace targeting. The reference company generator validates COMPANY_OAUTH_KV_ID, COMPANY_WORKSPACE_ID, COMPANY_LIST_ID, COMPANY_GITHUB_OWNER_ID, COMPANY_CLICKUP_USER_ID, and COMPANY_PUBLIC_ORIGIN. It targets a dedicated owner-only Worker; adapt it if you need an entirely separate tenancy model.
5. Trigger the matching GitHub Actions manual deployment, connect your MCP client to your own Worker HTTPS endpoint, complete both OAuth grants, and call service_info and get_clickup_connection_status to verify the deployed build and exclusive Workspace access.
6. Exercise reads first, then write/readback against an approved disposable task. Plan cleanup before creating records. Never rely on a task title alone for authorization.

Migration warning: This release renames the legacy staging Worker and the generic wrangler.jsonc project name. Existing staging URLs, OAuth callbacks, stored Worker state and custom client connectors do not automatically migrate. Reconfigure the new origin and Cloudflare resources before switching endpoints, and retire old infrastructure separately. The protected company Worker name is unchanged.

Known limitations

• ClickUp's public task-comment API does not document native table cells or a native horizontal-rule block; plain pipe tables and --- can display literally. Use a genuine task-description Markdown table or a label/value comment fallback.
• Docs Markdown can be lossy for editor-only tables, toggles, colors and other native components. Chat message and Docs cleanup coverage is not complete.
• There is no general rollback engine. A delete is destructive; ownership, Workspace bounds and explicit consent still matter. Some upstream features depend on ClickUp plan settings and API availability.
• Many older docs/ records are historical engineering evidence, not current instructions. The README and public release guide supersede stale operational claims in archived notes.
• Source is publicly readable; the connected private Worker, customer data, staff accounts and API keys are not public.

Project and community

Bug reports and feature proposals: GitHub Issues. Contributions: CONTRIBUTING.md. Report security issues privately, as described in SECURITY.md. See CHANGELOG.md for release changes.

License: MIT. ClickUp is a trademark of its respective owner; this project does not claim ClickUp endorsement.