@waterfallbridge/mcp

MCP (Model Context Protocol) server for WaterfallBridge — lets AI hosts such as Cursor, Codex CLI, and Claude Desktop prepare data, run waterfall / bridge variance analysis, and read results by driving the WaterfallBridge web app through Playwright.

This is the same code that ships inside the WaterfallBridge-Agent.exe desktop installer — only the packaging differs. The npm package targets users who already have Node.js and want a one-line, registry-friendly install; the EXE targets users who want a self-contained download with bundled Chromium and a system tray.

What it does

The server exposes a single tool suite over two transports:

• stdio MCP — spawned by an MCP host (Cursor / Codex / Claude Desktop).
• local HTTP / WebSocket — used by the in-app AI panel (optional).

Tools include open_app, login, upload_file, run_bridge, get_chart_data, prepare_bridge_xlsx, and a local-filesystem suite for AI-assisted data preparation. See the AI Integration Guide for the full reference.

Account required. Running analyses needs a WaterfallBridge account and an active subscription (server-side formulaBreakdown is subscription-gated).

Requirements

• Node.js >= 18

• Chromium — installed automatically on first launch via playwright install chromium (~150 MB, one time). You can also pre-install it manually:

  npx playwright install chromium

Use it from an MCP host

Cursor — ~/.cursor/mcp.json (or project .cursor/mcp.json)

{
  "mcpServers": {
    "waterfall-bridge": {
      "command": "npx",
      "args": ["-y", "@waterfallbridge/mcp", "--mode=stdio"],
      "env": { "WB_HEADLESS": "false" }
    }
  }
}

Codex CLI — ~/.codex/mcp.json

{
  "mcpServers": {
    "waterfall-bridge": {
      "command": "npx",
      "args": ["-y", "@waterfallbridge/mcp", "--mode=stdio"],
      "env": { "WB_HEADLESS": "false" }
    }
  }
}

Claude Desktop — claude_desktop_config.json

Same mcpServers block as above. On Windows the file lives at %APPDATA%\Claude\claude_desktop_config.json; on macOS at ~/Library/Application Support/Claude/claude_desktop_config.json.

Run directly

# stdio MCP server (what MCP hosts spawn)
npx -y @waterfallbridge/mcp --mode=stdio

# local HTTP/WS server (in-app AI panel, default port 39871)
npx -y @waterfallbridge/mcp --mode=local

Environment variables (common)

| Variable | Default | Purpose | |-------------------|----------------------------------------|-------------------------------------------| | WB_DEFAULT_URL | https://waterfallbridge.com/app/ | URL open_app opens when none is passed | | WB_HEADLESS | false (dev) / true (prod) | Run the automation Chromium headless | | WB_PORT | 39871 | Local HTTP/WS port (--mode=local) | | WB_DATA_DIR | OS-specific | Where sessions / credentials are stored |

The full list (filesystem allow-list, auth token, external MCP config, …) is documented in the project's AGENT_ARCHITECTURE.md.

License

MIT — see LICENSE.