# claude-handoff-mcp

> The first open-source MCP server for [Claude Design](https://claude.ai/design) handoff bundles.

Paste a Claude Design handoff URL in Cursor, Claude Code, Cline, Windsurf — or any MCP-compatible client — and the bundle materializes in your project, ready to ship.

```
Paste handoff URL  →  MCP fetches, extracts, summarizes the README,
                      and deploys files into your repo. One tool call.
```

## Why

Claude Design (Anthropic Labs, launched 2026-04-17) exports designs as **handoff URLs** served from `api.anthropic.com/v1/design/h/<hash>`. Today, consuming them means: download tar, extract, read README, figure out what to copy where. This MCP makes that one step in any agentic IDE.

- **Status:** community project. Not affiliated with Anthropic.
- **Scope:** wraps the publicly-served handoff bundle format. No scraping, no undocumented endpoints beyond the published handoff URL, no claude.ai session spoofing.

## Tools exposed

| Tool | What it does |
|---|---|
| `fetch_handoff(url)` | Download + extract the bundle to a temp dir. Detects HTML / PPTX / PDF. |
| `inspect_bundle(extract_dir)` | Summarize: README, entry HTML, file counts, 60-line preview. |
| `read_readme(extract_dir)` | Read the full handoff README (Claude Design always includes one). |
| `deploy_bundle(extract_dir, target, dest_dir)` | Copy files into a project folder or emit a JSON manifest. |

## Install

```bash
npm install -g @kiwuuu/claude-handoff-mcp
```

## Use in Claude Code

Add to your MCP config (`~/.claude.json` or wherever your client reads MCP servers):

```json
{
  "mcpServers": {
    "claude-handoff": {
      "command": "npx",
      "args": ["-y", "@kiwuuu/claude-handoff-mcp"]
    }
  }
}
```

Then in chat:

> Fetch https://api.anthropic.com/v1/design/h/abc123 and deploy it into ./public/

## Use in Cursor / Cline / Windsurf

Same config shape — point at the `npx` entry. See each client's MCP docs for the exact file.

## Use the CLI directly

```bash
npx claude-handoff one-shot https://api.anthropic.com/v1/design/h/abc123 ./my-app/public
```

## Caveats

- **Handoff URLs expire.** They have a TTL and may be single-use. The Share-menu export is the only way to get a fresh URL — there is no public listing endpoint. If `fetch_handoff` returns HTTP 404, the URL has aged out; re-export from claude.ai/design.
- **No API key used.** This tool calls only the public handoff URL. It does not require `ANTHROPIC_API_KEY`.
- **Format stability.** The bundle format is observed, not specified. If Anthropic changes it, this tool adapts or pauses.

## Contributing

Issues + PRs welcome. The core fetch/extract/deploy logic is <400 LOC in `src/core.ts` — easy to read, easy to fork.

## License

MIT. See [LICENSE](LICENSE).