kepler-mcp-demo

Drive the kepler.gl demo map from Claude / Codex through the @kepler.gl/mcp map surface — mapping-only, no analysis engine, no API key.

claude/codex ──Streamable HTTP MCP──▶ kepler-mcp-demo daemon (node)
  (or stdio spawn)                        │  /mcp   JSON-RPC for agents
                                          │  /ws    ▲ outbound (reverse connect)
                                          │  /files data for map.load-data
        https://kepler.gl/demo  ──────────┘

The kepler.gl demo page owns the map. It registers the map.* commands from @kepler.gl/mcp (getKeplerCommands(ctx)) against its own redux store and serves them over a WebSocket bridge. This node process is deliberately map-agnostic: the tool catalog comes from the page's connection, so the map surface is wholly owned by @kepler.gl/mcp.

What you get

The map.* commands the demo page serves (the DuckDB-free subset):

map.create-table / map.add-column / map.save-data need a DuckDB connector and are intentionally not exposed by the mapping-only bridge.

Related MCP server: Felt MCP

Run (daemon mode — recommended)

First install and build (and rebuild after any source change — a long-running daemon serves stale dist/):

pnpm install
pnpm build

Start the server

Foreground:

node dist/index.js --port 8765 --token mytoken --demo-url https://kepler.gl/demo

Detached (survives the terminal closing; log lands in /tmp/kepler-mcp-demo.log):

cd /path/to/kepler-mcp-demo && nohup node dist/index.js --port 8765 --token mytoken \
  --demo-url https://kepler.gl/demo > /tmp/kepler-mcp-demo.log 2>&1 &

Flags:

Check it's up:

curl -s http://localhost:8765/          # status page
lsof -nP -i :8765 -sTCP:LISTEN          # or check the listener
tail -f /tmp/kepler-mcp-demo.log        # see the banner + page connect/disconnect

Stop it:

lsof -ti :8765 | xargs kill

Start-once lifecycle

The daemon must be started once — not per session. Sessions (and claude mcp list health checks) just connect to it; the page stays connected across session restarts. You only need to run the start command again after a reboot, after killing the process, or after pnpm build.

1. Register the HTTP MCP server (once; pick the token so the page can use it):

   claude mcp add --transport http kepler-demo http://127.0.0.1:8765/mcp \
     --header "x-kepler-demo-token: <yours>"

2. Connect the page (once): open https://kepler.gl/demo (or the local demo-app) with ?mcp=<token>&mcpPort=8765, or toggle Connect to map harness and paste the token. It stays connected across session restarts — nothing to redo per session.

3. Start sessions freely. Each session initially sees only harness_status; the page's catalog arrives via a live tools/list_changed. Because the daemon owns the port, parallel sessions and health checks (claude mcp list) no longer collide.

Tip: register with -s user (claude mcp add -s user --transport http …) so the server is visible from any directory, not just the one you ran claude mcp add in.

Optional: auto-start with launchd (macOS)

To never think about starting the daemon again — it comes back after every reboot — create ~/Library/LaunchAgents/com.kepler-mcp-demo.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict>
  <key>Label</key><string>com.kepler-mcp-demo</string>
  <key>ProgramArguments</key><array>
    <string>/usr/local/bin/node</string>       <!-- or `which node` -->
    <string>/path/to/kepler-mcp-demo/dist/index.js</string>
    <string>--port</string><string>8765</string>
    <string>--token</string><string>mytoken</string>
  </array>
  <key>KeepAlive</key><true/>
  <key>RunAtLoad</key><true/>
  <key>StandardOutPath</key><string>/tmp/kepler-mcp-demo.log</string>
  <key>StandardErrorPath</key><string>/tmp/kepler-mcp-demo.log</string>
</dict></plist>

Then: launchctl load ~/Library/LaunchAgents/com.kepler-mcp-demo.plist.

Run (stdio — per-session spawn, also supported)

claude mcp add kepler-demo -- node /abs/path/to/kepler-mcp-demo/dist/index.js --port 8765 --token <yours>

Pass --port/--token so the page can connect to the instance the client spawns. The session starts first and the page connects second; the bridge pushes tools/list_changed so the map tools appear without a restart. Note the single-instance rule: while one such session is open, port 8765 is taken (the server exits with a legible message if not).

Security: the WS bridge requires the per-launch token; the static file server only serves the files/ directory (path-traversal blocked); the page connects out to your localhost, so a remote Claude cannot reach your browser.

Examples

• examples/random-points.prompt.md — the "generate 10,000 random points in the current map view" session.

Verify headlessly

pnpm smoke

Spawns the server, connects a fake page over WS, and exercises the MCP tools/list / tools/call round trip through the bridge.