MCP configuration

How it works

grip-mcp is a small Go program that connects to Chrome and exposes browser tools over MCP. Your AI client runs grip-mcp as a subprocess; Grip routes tool calls to the tab you have open in debugging Chrome.

Setup is three steps: launch Chrome with debugging, build grip-mcp, then paste a config block into your IDE or CLI. Most tools use the same shape — only the config file path and root JSON key differ.

Step 1 — Launch Chrome

Start Chrome with remote debugging enabled:

./scripts/launch-chrome.sh 9222

Use one debugging Chrome instance per port. If something else is on 9222, pick another port and set GRIP_CHROME_PORT to match.

Step 2 — Build grip-mcp

pnpm run build:mcp
# Creates bin/grip-mcp

Step 3 — Server config

Copy this block into your client's config. Replace the command path with your real path to bin/grip-mcp:

{
  "mcpServers": {
  "grip": {
    "command": "/path/to/grip/bin/grip-mcp",
    "env": {
      "GRIP_CHROME_PORT": "9222",
      "GRIP_LOG_LEVEL": "info"
    }
  }
  }
}

Then pick your tool below. You can also pass --port 9222 as a CLI arg instead of GRIP_CHROME_PORT where your client supports args.

Pick your client

Choose IDEs & editors or CLI & terminal, then select your app to see the exact config file, root key, and copy-paste snippet.

IDEs & editors7CLI & terminal8

CursorVS Code (GitHub Copilot)Windsurf (Codeium Cascade)ZedClaude DesktopJetBrains AI AssistantGoogle Antigravity

Cursor

Config: .cursor/mcp.json (project) · ~/.cursor/mcp.json (user)

Root key: mcpServers

Supports ${workspaceFolder} in command paths.

Official MCP docs →

Copy

{
  "mcpServers": {
    "grip": {
      "command": "${workspaceFolder}/bin/grip-mcp",
      "env": {
        "GRIP_CHROME_PORT": "9222",
        "GRIP_LOG_LEVEL": "info"
      }
    }
  }
}

CLI Agents & Daemon Mode

For command-line execution (e.g., using Claude Code or Gemini CLI), grip-mcp runs as a headless background subprocess rather than a visual application.

• Daemon Lifecycle: The host CLI agent starts grip-mcp automatically and communicates with it over standard input/output (stdio).
• CDP Connection: The background daemon hooks directly into Chrome via the remote debugging port (configured by GRIP_CHROME_PORT) using the Chrome DevTools Protocol.
• Global CLI Installation: If you use CLI tools globally, you can link the executable to your path:
  Copy

  # Link globally for easy access
  npm link
  # Or run direct from local path
  claude mcp add grip -- $(pwd)/bin/grip-mcp

Environment variables

MCP badge in Grip UI

The Grip popup, DevTools panel, and floating tray show a small MCP chip in the header so you can see connection status at a glance:

• Green — Chrome is reachable on your configured port
• Yellow — not set up yet; click for this guide

Troubleshooting

Badge stays yellow

• Is Chrome running with --remote-debugging-port=9222?
• Does GRIP_CHROME_PORT match your launch script?
• Restart your MCP client after editing config

Connection refused

Port 9222 may be in use, or Chrome wasn't started with debugging. Re-run launch-chrome.sh or choose a free port and update Chrome + MCP env together.

Server not loading

Config copied from the wrong app is the most common issue. VS Code wants servers, Zed wants context_servers, OpenCode wants mcp — check the root key in the client tab above.