@squidlerio/squidler-mcp

MCP proxy that sits between an AI client (Claude, Cursor, etc.) and the remote Squidler MCP server. It forwards all tools, resources, and prompts transparently, while adding local Chrome session management for testing localhost URLs.

How it works

AI Client (stdio) ←→ MCP Proxy ←→ Remote Squidler MCP (HTTP)
                        ↕
                   Local Chrome ←→ CDP Proxy (WebSocket)

The proxy intercepts test_case_run and test_case_run_standalone calls — when local Chrome mode is enabled, it automatically creates a CDP session and routes the test through your local browser instead of the cloud worker's Chrome. Same handling applies to test_cases_run_all and test_cases_run_by_label.

Related MCP server: chrome-faithful

Quick Start

Run directly with npx — no install or API key needed:

npx @squidlerio/squidler-mcp

On first use, a browser window opens for you to sign in to Squidler. Your session is saved locally so you only need to do this once.

Claude Code

claude mcp add squidler -- npx -y @squidlerio/squidler-mcp

Cursor / Other MCP Clients

Add to your MCP client configuration:

{
  "mcpServers": {
    "squidler": {
      "command": "npx",
      "args": ["-y", "@squidlerio/squidler-mcp"]
    }
  }
}

CLI Commands

# Sign in to Squidler (happens automatically on first use)
squidler-mcp login

# Sign out and clear saved session
squidler-mcp logout

# Download Chrome headless shell for local testing
squidler-mcp download-chrome

Local Session Tools

These tools are added by the proxy (not available on the remote server):

• local_session_start — Enable local Chrome mode. Accepts headless (boolean, default: true). Chrome is launched on the first test-running tool call.

• local_session_stop — Disable local Chrome mode and stop any active session.

• local_session_status — Check if local Chrome mode is enabled and if a session is active.

When local Chrome mode is enabled, the test-running tools — test_case_run, test_case_run_standalone, test_cases_run_all, test_cases_run_by_label — automatically create/recycle a CDP session and route through your local Chrome. Back-to-back tests get a fresh Chrome instance each time.

Advanced: API Key Override

If you prefer to use an API key instead of OAuth login, set the SQUIDLER_API_KEY environment variable:

{
  "mcpServers": {
    "squidler": {
      "command": "npx",
      "args": ["-y", "@squidlerio/squidler-mcp"],
      "env": {
        "SQUIDLER_API_KEY": "your-api-key"
      }
    }
  }
}

Development

bun install
bun run start          # Run CLI
bun run mcp-proxy      # Run MCP proxy
bun run build          # Build for npm publishing