claude-preview-mcp

Dev-server lifecycle + Chrome browser automation, as an MCP server. The preview_* tool family that any MCP-compatible agent can use.

This is the Anthropic Claude_Preview plugin re-implemented as a standalone MCP server so it works in Claude Code, OpenCode, Kilo Code, and any other MCP-compatible agent — with one canonical launch.json per project.

The repo ships the patched-upstream source (TypeScript) + pre-built JS, so installs don't need a build step. A single install.sh handles all three target agents.

What you get

mcp__Claude_Preview__preview_* tools (14 total):

Browser-required tools use the system's Chrome (/Applications/Google Chrome.app on macOS, google-chrome / chromium on Linux).

Related MCP server: @nimbus21.ai/chrome-devtools-mcp

Install (RECOMMENDED: Claude Code as a plugin)

# 1. Clone
git clone https://github.com/MichaelTendoSsemwanga/claude-preview-mcp
cd claude-preview-mcp

# 2. Pick your agent
./scripts/install.sh claude-code   # one-line: plugin cache, plugin.json, done
./scripts/install.sh opencode      # ~/tools + ~/.config/opencode/opencode.jsonc
./scripts/install.sh kilo          # ~/tools + ~/.kilocode/mcp_settings.json
./scripts/install.sh all           # all three

install.sh:

• Copies the committed build/ into the right agent location

• Provisions node_modules/ (just @modelcontextprotocol/sdk + puppeteer-core, ~25MB) into the same location via a temp scratch dir — so the repo itself stays light

• Writes / merges the MCP config (uses jq for an atomic JSON merge that preserves any existing config)

• Restores .claude-plugin/plugin.json for Claude Code

Per-agent activate

Why Claude Code is recommended

• One-line setup (drop the plugin into the cache, no MCP config to touch)

• Plugin lifecycle is managed by Claude Code — auto-spawned on launch, auto-killed on exit

• The plugin.json uses ${CLAUDE_PLUGIN_ROOT} so the install path is stable across moves/upgrades

• Same launch.json file works in Claude Code's built-in preview (which uses the configurations format) AND this MCP

Why other agents

OpenCode and Kilo don't have a plugin system. They register MCP servers by hand-rolling a config file, and they don't ship a configurations preview concept. This MCP bridges that gap: they get the same dev-server workflow, using the same launch.json, just with the extra hop of an MCP server entry in their config.

.claude/launch.json (the only project-side file)

The MCP server reads dev-server definitions from <project>/.claude/launch.json, walking upward from the agent's process.cwd() until it finds one. Two formats supported, picked in priority order:

Claude Code format (preferred)

{
  "version": "0.0.0",
  "configurations": [
    {
      "name": "back-office",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "port": 5173
    },
    {
      "name": "tkt-backend",
      "runtimeExecutable": "bash",
      "runtimeArgs": ["-c", "cd /Users/loft/tkt-backend && bun run --hot src/index.ts"],
      "port": 3001
    }
  ]
}

Fields: name, runtimeExecutable, runtimeArgs (array), port, autoPort (advisory), env (object), url (optional — overrides the synthesized http://localhost:{port}).

The MCP translates internally: runtimeExecutable→command, runtimeArgs→args, port→url.

Legacy servers format (still supported)

{
  "servers": [
    {
      "name": "web",
      "command": "npm",
      "args": ["run", "dev"],
      "url": "http://localhost:3000",
      "readyPattern": "Local:"
    }
  ]
}

Use this if you have a project that already used it. Don't mix the two formats in the same file (only configurations is read when both are present).

Repo layout

claude-preview-mcp/
├── .claude-plugin/
│   └── plugin.json          # Claude Code plugin manifest
├── src/                     # TypeScript source (patches live here)
│   ├── index.ts             #   MCP server entry, tool definitions, handlers
│   ├── process-manager.ts   #   launch.json parser + dev-server spawn
│   ├── browser-manager.ts   #   headless Chrome session
│   └── schemas.ts           #   zod input schemas
├── build/                   # Pre-compiled JS (committed; don't need to build)
│   └── *.js, *.js.map
├── scripts/
│   └── install.sh           # Universal installer (claude-code | opencode | kilo | all)
├── docs/
│   └── ARCHITECTURE.md      # Claude Code plugin internals + MCP protocol details
├── package.json             # Name, deps, build script
├── package-lock.json        # Locked dep versions
├── tsconfig.json            # TS compiler config (Node16 ESM, strict)
├── .gitignore
├── LICENSE                  # MIT
└── README.md                # this file

Develop / rebuild

# Edit src/*.ts
npm install            # one time, fetches dev deps
npm run build          # tsc → build/
git add build/ src/    # commit both

The install script will use the freshly-built build/ on the next run.

Smoke test (any agent)

In the agent's session:

1. mcp__Claude_Preview__preview_list → returns {configured: [...], running: []}

2. mcp__Claude_Preview__preview_start {"name": "<one-of-your-configurations>"} → starts it

3. mcp__Claude_Preview__preview_list → now shows it in running[]

4. (browser) preview_navigate {"url": "http://localhost:5173"} then preview_snapshot

5. preview_logs {"name": "<name>", "tail": 50} → see the dev-server output

6. preview_stop {"name": "<name>"} → SIGTERM

Or from the shell, no agent needed:

node ./build/index.js &
sleep 1
# Talk JSON-RPC to stdin/stdout (use the test script in /tmp, or any MCP client)
kill %1

What's patched vs upstream

The Anthropic Claude_Preview plugin (this repo's source) ships with four bugs that surface under modern MCP clients (Claude Code, OpenCode 1.17+ — both use protocol 2025-11-25). All four are fixed in src/:

Each patch has an inline comment explaining the original cause. See docs/ARCHITECTURE.md for the long version with the diagnostic traces.

Caveats

• One Chrome per MCP server. If you have this AND chrome-devtools-mcp registered, each spawns its own Chrome instance. Don't run both pointing at the same page.

• One dev server per port. Two preview systems (Claude Code's built-in + this MCP) can't both bind the same port. Use one per project.

• Process state isn't shared. Servers started via this MCP die when the MCP process exits. Claude Code's built-in preview is more durable.

• launch.json walks up. If you run an agent from ~/ expecting project launch files, it won't — cd into the project root first.

• Per-agent permissions. Most agents prompt on first tool use. Allowlist Claude_Preview (or each individual tool) to stop the prompts. The Kilo Code install includes an alwaysAllow block by default.

• macOS Chrome path is hard-coded in browser-manager.ts (looks for /Applications/Google Chrome.app/Contents/MacOS/Google Chrome first, then google-chrome on PATH). Override with CHROME_PATH env var.

License

MIT — see LICENSE. Bundled dependencies (@modelcontextprotocol/sdk, puppeteer-core) retain their own licenses.