cy-agent-bridge — Cytoscape Web MCP Server

An MCP (Model Context Protocol) server that connects Claude to a running Cytoscape Web instance via Chrome DevTools Protocol (CDP). This enables Claude to read and manipulate networks, tables, visual styles, and more through natural language.

Split out of cytoscape-web-app-examples, where it lived as the claude-bridge/ workspace. That repository is a set of small, readable App API examples; this is a product with its own MCP server, so it now has its own repository and release cycle. The federation id (claudeBridge), the dev port (6100) and the package names are unchanged.

The host application is cytoscape-web, which serves the app on localhost:5500 in development.

Architecture

Claude Code ←→ MCP (stdio) ←→ mcp-server ←→ CDP (WebSocket) ←→ Chrome ←→ Cytoscape Web

• MF Plugin (src/): A Cytoscape Web app that shows connection status in the right panel.

• MCP Server (mcp-server/): A Node.js process that exposes 57 tools to Claude via MCP, executing them against the browser through CDP page.evaluate().

Related MCP server: Chrome DevTools MCP

Quick Start

1. Start Cytoscape Web

cd cytoscape-web
npm run dev          # → http://localhost:5500

2. Start Chrome with remote debugging

macOS / Linux (native)

google-chrome --remote-debugging-port=9222

Then open http://localhost:5500 in the launched Chrome window.

WSL2 on Windows

WSL2 requires extra setup because Chrome runs on the Windows host while the MCP server runs inside the WSL2 VM.

Step 1 — Launch Chrome (PowerShell):

& "C:\Program Files\Google\Chrome\Application\chrome.exe" `
  --remote-debugging-port=9222 `
  --remote-debugging-address=0.0.0.0 `
  --remote-allow-origins=* `
  --user-data-dir="$env:TEMP\chrome-debug"

--remote-debugging-address=0.0.0.0 binds to all interfaces. --remote-allow-origins=* allows non-localhost CDP connections.

Step 2 — Port proxy (admin PowerShell, one-time):

netsh interface portproxy add v4tov4 `
  listenport=9222 listenaddress=0.0.0.0 `
  connectport=9222 connectaddress=127.0.0.1

Step 3 — Firewall rule (admin PowerShell, one-time):

New-NetFirewallRule -DisplayName "Chrome CDP WSL" `
  -Direction Inbound -LocalPort 9222 -Protocol TCP `
  -Action Allow -Profile Any

Step 4 — Find the gateway IP (WSL2):

ip route show default | awk '{print $3}'
# → e.g. 172.20.112.1

Step 5 — Verify (WSL2):

curl -s http://172.20.112.1:9222/json/version | head -3

You should see a JSON response with "Browser": "Chrome/...".

Open http://localhost:5500 in the launched Chrome window.

3. Build and run the MCP server

cd mcp-server
npm install
npm run build
node dist/server.js                                     # native Linux/macOS
node dist/server.js --cdp-url http://172.20.112.1:9222  # WSL2

You should see:

[claude-bridge] Connected to Cytoscape Web via CDP
[claude-bridge] MCP server running on stdio

4. Register as an MCP server in Claude Code

Add to your .claude/settings.json:

{
  "mcpServers": {
    "cytoscape": {
      "command": "node",
      "args": [
        "/path/to/cy-agent-bridge/mcp-server/dist/server.js",
        "--cdp-url", "http://172.20.112.1:9222"
      ]
    }
  }
}

Omit --cdp-url on native Linux/macOS (defaults to http://localhost:9222).

5. Run the app panel (optional)

The MCP server drives the host on its own; the panel is the live log of what it sent. It is a Module Federation remote, so the host loads it over HTTP:

npm install
npm run dev          # → http://localhost:6100

The dev server prints an install link. Open it against a host on the same origin family (the host only installs a localhost app when the host itself is on localhost):

http://localhost:5500/?installApp=http://localhost:6100/cyweb-app.json

The browser asks for permission the first time. The panel then appears in the host's right panel.

Available Tools (57)

All tools are prefixed with cytoscape_ (e.g., cytoscape_get_workspace).

Design Documents

• Design Overview

• Implementation Plan

• MCP Tool Signatures

• Scenarios

• ADRs

Documents above describe the bridge as built. Planned work lives in its own subdirectory:

• Agent Workflow · checklist · open proposals — making the analysis-to-visualisation workflow run, and the bridge vendor-neutral