Quick start

Before you start

Make sure you have:

• Node.js 20+ and pnpm
• Google Chrome — for the extension and browser automation
• Go 1.22+ — or let pnpm run build:mcp install a local Go toolchain for you

Install & build

Clone the repo and install dependencies using your preferred package manager (pnpm is recommended):

git clone <repo-url> grip
cd grip

# Using pnpm (recommended)
pnpm install
pnpm turbo build
pnpm run build:mcp

# Using npm
npm install
npm run build
npm run build:mcp

# Using yarn
yarn install
yarn build
yarn build:mcp

# Using bun
bun install
bun run build
bun run build:mcp

When this finishes, you should have bin/grip-mcp ready and the extension build in packages/extension/dist.

Launch Chrome

Grip talks to Chrome over the remote debugging port (default 9222). Use the helper script so you don't have to remember flags:

./scripts/launch-chrome.sh 9222

Keep this Chrome window open while you use Grip or MCP. Closing it breaks the connection.

Load the extension

Build and load the unpacked extension in Chrome:

pnpm --filter @grip/extension build

Then in Chrome:

1. Open chrome://extensions
2. Turn on Developer mode
3. Click Load unpacked and choose packages/extension/dist

For day-to-day development with reload on save:

# Using pnpm
pnpm --filter @grip/extension dev

# Using npm
npm run dev --workspace=packages/extension

# Using yarn
yarn workspace @grip/extension dev

# Using bun
bun --filter @grip/extension dev

Connect MCP

Add grip-mcp to your editor or CLI. The exact file depends on your tool — see the full MCP configuration guide for Cursor, VS Code, Claude Code, Gemini CLI, OpenCode, and others.

Here is a minimal example (works in Cursor and most mcpServers clients):

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

Use an absolute path to grip-mcp if your tool's working directory is not the repo root.

Check it works

MCP badge

Open Grip from the extension icon, DevTools panel, or floating tray. Look at the MCP chip in the header:

• Green — Chrome is reachable on port 9222. You're good to go.
• Yellow — not connected yet. Click the chip for setup help, or follow the MCP configuration guide.

Pick an element

Click Pick, then click anything on the page. You should see it in pick history with tag, role, CSS, XPath, and optional comment — that confirms the full loop is working.