@iqsteel/mcp-bridge

MCP server that bridges Claude Desktop (or any MCP client) to a running ifc-viewer browser tab via WebSocket.

How it works

Claude Desktop  ←(stdio MCP)→  @iqsteel/mcp-bridge  ←(WebSocket)→  ifc-viewer tab

• The viewer (browser) opens the WebSocket as a client — browsers can't listen() on a port.
• The bridge opens a WebSocket server on 127.0.0.1:<port> and waits for the viewer to dial in.
• Authentication uses a pairing token displayed in the viewer's Settings → MCP section. The same value goes into the bridge CLI args and the Claude Desktop config.

Step 7 (current): read-only tools — list_models, get_model_summary, get_spatial_tree, get_element, query_elements, get_selection, get_camera_state.

Write tools (select_elements, set_visibility, focus_camera, set_color, run_script) land in Step 8 — gated per-tool from Settings.

Install / run

The bridge is published to npm so Claude Desktop can spawn it via npx:

npx -y @iqsteel/mcp-bridge --port 7800 --token <paired-token>

--token is required. Get it from ifc-viewer → AI tab → Settings → MCP section → Pairing token.

Claude Desktop config

Add to claude_desktop_config.json (under mcpServers):

{
  "mcpServers": {
    "iqsteel": {
      "command": "npx",
      "args": ["-y", "@iqsteel/mcp-bridge", "--port", "7800", "--token", "PASTE_TOKEN_HERE"]
    }
  }
}

Config locations:

| OS | Path | |---------|------------------------------------------------------------| | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\Claude\claude_desktop_config.json |

Restart Claude Desktop after editing.

Connecting

1. Open the viewer in your browser.
2. Open AI tab → Settings → expand the MCP section. Copy the pairing token.
3. Paste it into the Claude Desktop config (or run the bridge directly).
4. Restart Claude Desktop. The bridge spawns, waits for the viewer.
5. In the viewer, click Connect in the MCP section. Status flips to "✓ Connected to bridge."
6. In Claude Desktop, ask it to call any of the read tools — e.g. "List the IFC models loaded in the viewer."

If the viewer is closed or refreshed, click Connect again. The bridge stays alive until Claude Desktop closes it.

Security notes

• The bridge listens on 127.0.0.1 only — no remote network access. Use --host 0.0.0.0 only if you understand the implications (anyone on your network could connect to your viewer).
• The pairing token is a 32-char base64url secret. Treat it like a password. Revoke from the viewer when you're done; the bridge will refuse the old token afterwards.
• Read tools are safe — they read viewer state, no mutations. Write tools (Step 8) are gated by an explicit toggle.

Troubleshooting

| Symptom | Likely cause | |----------------------------------|--------------------------------------------------------------| | Bridge refused: code 4401 | Token mismatch. Re-copy from viewer Settings. | | connect ECONNREFUSED | Bridge not running, or wrong port. | | Tools time out (30s) | Viewer hasn't connected yet (click Connect in Settings). | | Claude Desktop doesn't see tools | Restart Claude Desktop after editing the config file. |