Skip to main content
The MCP integration allows React Grab to communicate with AI tools that support the Model Context Protocol. This provides a standardized way to share UI context with various AI assistants.

​
What is MCP?

Model Context Protocol (MCP) is a standardized protocol for sharing context between applications and AI tools. React Grab’s MCP integration enables you to:
  • Share selected UI elements with MCP-compatible AI tools
  • Automatically send context when you copy elements
  • Stream UI selections to your AI assistant in real-time

​
Installation

1

Install the package

npm install @react-grab/mcp
# or
pnpm add @react-grab/mcp
# or
bun add @react-grab/mcp
# or
yarn add @react-grab/mcp
2

Start the MCP server

The MCP server runs on port 7567 by default and handles communication between React Grab and MCP-compatible tools.

​
Quick Start (CLI)

Start the server before running your dev server:
npx @react-grab/mcp@latest && pnpm run dev
The server runs as a detached background process. Stopping your dev server (Ctrl+C) won’t stop the MCP server.
To stop the server:
pkill -f "react-grab.*server"
3

Add the client to your app

Choose your framework:

​
Script Tag

<script src="//unpkg.com/react-grab/dist/index.global.js"></script>
<script src="//unpkg.com/@react-grab/mcp/dist/client.global.js"></script>

​
Next.js

Add to your app/layout.tsx:
import Script from "next/script";

export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        {process.env.NODE_ENV === "development" && (
          <>
            <Script
              src="//unpkg.com/react-grab/dist/index.global.js"
              strategy="beforeInteractive"
            />
            <Script
              src="//unpkg.com/@react-grab/mcp/dist/client.global.js"
              strategy="lazyOnload"
            />
          </>
        )}
      </head>
      <body>{children}</body>
    </html>
  );
}

​
ES Module

import { attachMcpPlugin } from "@react-grab/mcp/client";

attachMcpPlugin();
For better lifecycle management, start the server from your config file. This ensures the server stops when your dev server stops:

​
Vite

// vite.config.ts
import { startMcpServer } from "@react-grab/mcp/server";

if (process.env.NODE_ENV === "development") {
  startMcpServer();
}

​
Next.js

// next.config.ts
import { startMcpServer } from "@react-grab/mcp/server";

if (process.env.NODE_ENV === "development") {
  startMcpServer();
}

​
How It Works

┌─────────────────┐      HTTP       ┌─────────────────┐      MCP       ┌─────────────────┐
│                 │  localhost:7567 │                 │                │                 │
│   React Grab    │ ──────────────► │   MCP Server    │ ─────────────► │   AI Tools      │
│    (Browser)    │ ◄────────────── │   (Node.js)     │ ◄───────────── │   (via MCP)     │
│                 │                 │                 │                │                 │
└─────────────────┘                 └─────────────────┘                └─────────────────┘
      Client                              Server                            Tools
  1. React Grab sends selected element context to the MCP server via HTTP POST
  2. MCP Server stores the context and makes it available via the MCP protocol
  3. AI Tools can query the server to retrieve the latest UI context
  4. The context includes HTML structure, component info, and optional user prompts

​
Using with AI Tools

Once the MCP server is running, AI tools can use the get_element_context tool to retrieve the latest context you’ve selected in React Grab.

​
Context Format

The MCP server provides context in this format: 
Prompt: [Your custom prompt if provided]

Elements:
<button class="submit-btn">Submit</button>
in SubmitButton at components/form.tsx:42:10

​
Context Expiration

Context automatically expires after a certain time to prevent stale data from being used. The server tracks when context was submitted and clears it after the TTL expires.

​
Server Options

You can customize the MCP server: 
import { startMcpServer } from "@react-grab/mcp/server";

startMcpServer({
  port: 7567,        // Custom port (default: 7567)
  stdio: false,      // Use stdio transport instead of HTTP (default: false)
});

​
STDIO Mode

For direct integration with MCP-compatible tools that use stdin/stdout: 
react-grab-mcp --stdio
This mode starts the MCP server using stdio transport while also running an HTTP server for receiving context from the browser.

​
Troubleshooting

  • Check if port 7567 is already in use
  • Try killing any existing processes: pkill -f "react-grab.*server"
  • Check server logs for error messages
  • Verify the MCP server is running by checking http://localhost:7567/health
  • Make sure your AI tool is configured to connect to the React Grab MCP server
  • Check that the context hasn’t expired (try selecting an element again)
  • Ensure the server is running before loading your app
  • Check browser console for CORS or connection errors
  • Verify the server URL matches the configured port

​
Next Steps

Plugin API

Learn about the plugin system and hooks

Configuration

Customize React Grab behavior

Build docs developers (and LLMs) love

Get started for freeTalk to us