@tempo-ai/mcp
v0.0.151
Published
Tempo MCP server for Claude Code, Codex, Cursor, and any other MCP-compatible host. One server exposing Tempo's issues, docs, comments, agents, scripts, Slack, Linear, and canvas toolsets.
Readme
Tempo MCP
Tempo ships two MCP surfaces. They expose the same underlying tools — pick by where your AI runs.
Which one do I install?
| Where your AI runs | Install this | What you get |
| --- | --- | --- |
| A coding agent on your machine — Claude Code, Codex CLI, Cursor, any stdio MCP host | @tempo-ai/mcp (npm, local) — see Local package | The FULL suite: issues, docs, comments, agents, scripts, Slack, Linear, live desktop selection context — reads and writes — plus canvas/design tools (screenshots, share links) when run inside a Tempo repo |
| A chat app in the browser or on mobile — ChatGPT, claude.ai, Claude mobile, or any client that takes a remote MCP URL | https://mcp.tempo.new/mcp (hosted) — see Hosted server | The DB-backed toolsets, reads and writes: issues, docs, comments, agents, scripts, Slack, Linear, plus live desktop selection context through Convex. Filesystem canvas authoring requires the local package |
Rules of thumb:
- If the client can run
npx, use the local package — it's the full experience. - If all you can give the client is a URL, use the hosted server.
- Never configure both in one client; the hosted tools are a subset of the local ones.
Local package (@tempo-ai/mcp)
One server entry exposes Tempo's full tool surface: issues, cloud docs,
canvas comments, custom agents, run scripts, Slack (as the org's Tempo
bot), Linear, and — when run inside a Tempo repo — the canvas tools,
including headless canvas_screenshot and canvas_share with real
preview capture, plus canvas_verify_vrt for VRT stability checks.
Install
One command, no account needed first. Claude Code:
claude mcp add tempo -- npx -y @tempo-ai/mcpCodex (~/.codex/config.toml):
[mcp_servers.tempo]
command = "npx"
args = ["-y", "@tempo-ai/mcp"]Cursor / generic JSON config:
{ "tempo": { "command": "npx", "args": ["-y", "@tempo-ai/mcp"] } }Then just use a Tempo tool ("list my Tempo issues"). The first one that needs your account opens the browser to sign in — or sign up, which walks you through creating your organization — and the tool continues once you're back. No login command, no restart. Later sessions connect silently; if your session ever expires, the next tool call prompts again.
Optional: sign in ahead of time with npx -y @tempo-ai/mcp login, or set
TEMPO_AUTH_TOKEN where no browser exists (see the install guide).
Flags
--toolsets issues,docs,canvas— serve only the named toolsets--readonly— register no write tools at all (alsoTEMPO_MCP_READONLY=1)
Live desktop selection context (local and hosted)
The design-context toolset works outside a local repository, including on
hosted MCP. Keep Tempo open and signed into the same account and organization:
- Call
tempo_list_orgsto find theorgId. - Call
list_design_context_targets({ orgId })to find an open canvas. - Select elements or storyboards in Tempo, then call
get_design_context({ orgId, targetId }).
The result contains the same selection metadata as Cmd+L (source locations,
classes, ancestors, storyboard identity and rendering errors), plus PNG image
blocks when capture succeeds. It does not attach anything to a Tempo chat or
export full DOM/CSS. Both tools remain available with --readonly / ?readonly=1.
Multiple canvases require an explicit targetId. Closed, changed, empty, or
offline selections return errors instead of silently choosing another canvas.
Captures are on demand through Convex, limited to 20 items / 8 MiB, and expire
within 30 seconds if the desktop does not answer. Private snapshot blobs are
purged five minutes after that deadline. No desktop port or remote-control
feature flag is required; the workspace must resolve to a registered org project.
Canvas visuals
canvas_screenshot, canvas_verify_vrt, and canvas_share
capture with headless Chromium (the same pipeline Tempo's visual-review CI
uses). Stability runs share one devserver/browser while isolating each render.
They require Playwright's Chromium once per machine:
npx playwright install chromiumCanvas capture uses the capture SDK runtime bundled inside @tempo-ai/mcp.
MCP does not install the visual-review CLI. The public tempo-sdk stays
minimal, and no separate runtime download or credentials are needed. TEMPO_SDK_RUNTIME_PATH can select an explicitly
provisioned compatible provider instead.
Share links require the canvas's branch to be committed and pushed.
Visual review setup
visual_review_doctor diagnoses a repo's visual-review setup one layer at
a time, visual_review_init writes the .github/workflows/visual-review.yml
the published @tempo-ai/visual-review CLI expects (never overwriting an
existing one), and canvas_set_vrt writes a storyboard's vrt prop through
the same editor the in-app Track toggle uses. Outside the Tempo app the
doctor's Tempo-registration, GitHub-App, and branch-protection rows read
null (unavailable), never a guess.
Hosted server (mcp.tempo.new)
A remote MCP server (streamable HTTP + OAuth 2.1). You paste one URL, the
client walks you through a Clerk sign-in consent, and every call runs as
your Tempo account — reads and writes, with org membership re-validated
server-side on every call. Only connect clients you trust: an authorized
connector acts as you. Add ?readonly=1 to the URL for a connection that
can never write.
The URL for every client:
https://mcp.tempo.new/mcpChatGPT (web)
- Enable connector development: Settings → Apps & Connectors → Advanced settings → enable Developer mode.
- Settings → Apps & Connectors → Create (custom connector) → paste
https://mcp.tempo.new/mcp, authentication OAuth. - Approve the Tempo sign-in consent when prompted.
- In a chat, enable the connector under Plus → More → Developer mode.
Note: without Developer mode, ChatGPT connectors only run search-style deep-research tools; Developer mode unlocks full tool calling.
claude.ai (web) and Claude mobile
- Settings → Connectors → Add custom connector.
- Paste
https://mcp.tempo.new/mcp, then complete the OAuth consent.
Claude Code / Cursor (remote instead of local)
Prefer the local package (more tools). But the hosted URL also works:
claude mcp add --transport http tempo-hosted https://mcp.tempo.new/mcpConnection options
?toolsets=issues,docs— serve only the named toolsets (valid: issues, docs, comments, agents, scripts, slack, linear, design-context)?readonly=1— strict opt-down: write tools are never registered on this connection, whatever else is configured
Scoping model (both surfaces)
Identity comes from your sign-in; SCOPE is explicit on every call. Each
tool requires an orgId argument (and projectId where project-scoped) —
the AI discovers both with the built-in tempo_list_orgs /
tempo_list_projects tools. Nothing org-related is ever baked into the
connection config, and Tempo's backend re-validates org membership on
every function call regardless.
Hosted architecture (maintainers)
The endpoint lives in the web-auth Vercel deployable
(tempo-client/web-auth/api/mcp.ts + rewrites) and instantiates the same
factory modules as this package via @tempo-modules/mcp-hosted: Clerk
OAuth token verified per request → 60s ES256 service JWT minted for
Convex (additive customJwt provider in auth.config.ts) → stateless
streamable HTTP, fresh server instance per POST. Ops runbook:
tempo-client/web-auth/CLAUDE.md → "Hosted MCP".
