React Context MCP

<div align="center"> <img src="logo.png" alt="React Context MCP" width="600"> <br><br>

</div>

Instant React Component Discovery for AI Assistants

The Problem: You see a "Sign up" button and need to find which React component renders it, what file it's in, and what props it has.

With React Context MCP: Ask your AI assistant and get a complete component tree with accessibility information instantly.

// You ask your AI:
"Show me the component tree for this page"

// Your AI calls:
get_component_map()

// You get:
React Component Tree:

OnboardingPage (src/pages/OnboardingPage.tsx:25:4)
└─ OnboardingScreen {content={...}, onSignUp={fn}, onLogIn={fn}} (src/pages/OnboardingPage.tsx:136:8)
   └─ Box {display="flex", flexDirection="column"} (src/design-system/OnboardingScreen.tsx:138:4)
      └─ Typography {as="h1", variant="h2Bold"} [role="heading" name="Create Account"] (src/components/Typography.tsx:103:10)
         └─ h1 [role="heading" name="Create Account"]
      └─ Button {size="large", onClick={fn}} [role="button" name="Sign up"] (src/components/Button.tsx:115:12)
         └─ button [role="button" name="Sign up"]

---

What You Can Do

Ask your AI assistant to:

• Get complete component trees - See all React components with props, source locations, and accessibility structure
• Find any UI element - Trace buttons, inputs, or any element to its React component
• Inspect component details - Get props, state, and owner chains for any component
• Navigate multi-page flows - Analyze components across different screens

react-context-mcp is a Model Context Protocol (MCP) server that connects your AI assistant to React applications running in Chrome, providing instant access to component trees, props, state, and source locations.

How It Works

The Complete Picture: get_component_map

When you ask "Show me the component tree", your AI calls:

get_component_map({ verbose: true })

Returns a markdown tree showing:

• All React components (Button, TextField, OnboardingScreen, etc.)
• Component props in JSX format (size="large", onClick={fn})
• Accessibility information (role, accessible name for screen readers)
• DOM elements with semantic roles (button, h1, p, img)
• Source locations (file:line:column)

React Component Tree:

App (src/main.tsx:8:4)
└─ OnboardingScreen {onSignUp={fn}, onLogIn={fn}} (src/pages/OnboardingPage.tsx:136:8)
   └─ Stack {direction="column", gap="3"} (src/design-system/OnboardingScreen.tsx:216:8)
      └─ Text {variant="h1"} [role="heading" name="Send instantly"] (src/components/Text.tsx:222:12)
         └─ h1 [role="heading" name="Send instantly"]
      └─ Text {variant="body-secondary"} [role="paragraph"] (src/components/Text.tsx:232:12)
         └─ p [role="paragraph"]
      └─ Button {variant="primary", size="large"} [role="button" name="Sign up"] (src/components/Button.tsx:361:10)
         └─ button [role="button" name="Sign up"]

Focused Element Inspection

For specific element details, use the two-step process:

Step 1: Take a snapshot to get element IDs

take_snapshot({ verbose: true })

Returns the accessibility tree with backendDOMNodeId for every element:

{
  "role": "button",
  "name": "Sign up",
  "backendDOMNodeId": 48
}

Step 2: Get React component details

get_react_component_from_backend_node_id(48)

Returns complete component information:

{
  "component": {
    "name": "Button",
    "type": "ForwardRef",
    "source": {
      "fileName": "src/components/Button.tsx",
      "lineNumber": 42,
      "columnNumber": 8
    },
    "props": {
      "variant": "primary",
      "size": "large",
      "onClick": "[Function]",
      "children": "Sign up"
    },
    "owners": [
      {
        "name": "OnboardingScreen",
        "source": "src/screens/OnboardingScreen.tsx:222:12"
      }
    ]
  }
}

---

Requirements

• Node.js v20.19+ or v22.12+ or v23+
• Chrome current stable version
• React application with development build (for source location tracking)

Getting Started

Quick Install

Add to your MCP client configuration:

{
  "mcpServers": {
    "react-context": {
      "command": "npx",
      "args": ["-y", "react-context-mcp@latest"]
    }
  }
}

[!NOTE] Using @latest ensures you always get the most recent version.

MCP Client Setup

<details> <summary><b>Claude Code</b></summary>

Use the Claude Code CLI:

claude mcp add react-context npx react-context-mcp@latest

</details>

<details> <summary><b>Cursor</b></summary>

Go to Cursor Settings → MCP → New MCP Server, then add:

{
  "mcpServers": {
    "react-context": {
      "command": "npx",
      "args": ["-y", "react-context-mcp@latest"]
    }
  }
}

</details>

<details> <summary><b>Cline / Windsurf / Other Clients</b></summary>

Add the configuration above to your MCP settings file. Refer to your client's documentation for the config file location.

</details>

First Prompt

Try this in your MCP client:

Navigate to http://localhost:3000 and show me the component tree

Your AI assistant will open the browser, navigate to the page, and display the complete React component hierarchy with accessibility information.

Source Location Tracking

⚠️ IMPORTANT: To get accurate component source locations (file name, line number), you must configure the Babel plugin in your React project.

Why Is This Required?

React Context MCP extracts source locations from data-inspector-* DOM attributes added by Babel. React 19 removed the _debugSource fiber property, making the Babel plugin approach the only reliable method for source tracking.

Without the plugin:

• ❌ Component source locations will show as undefined
• ✅ Component names, props, and tree structure work normally

With the plugin:

• ✅ Exact file paths (e.g., src/components/Button.tsx)
• ✅ Precise line and column numbers
• ✅ Complete component hierarchy with sources

Configuration

Vite

npm install --save-dev @react-dev-inspector/babel-plugin

Add to vite.config.ts:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [
    react({
      babel: {
        plugins: [
          ['@react-dev-inspector/babel-plugin', {
            excludes: ['node_modules']
          }]
        ]
      }
    })
  ]
})

Next.js / CRA / Manual Babel

See the detailed configuration instructions for Next.js, Create React App, and manual Babel setup in the react-dev-inspector documentation.

---

MCP Tools

Page Management (5 tools)

1. list_pages - List all open browser tabs
2. select_page - Select a tab to work with
3. close_page - Close a specific tab
4. new_page - Open a new tab and navigate to URL
5. navigate_page - Navigate, reload, or go back/forward

React Inspection (3 tools)

get_component_map

Primary tool - Get complete React component tree as markdown

Arguments:

• verbose (boolean, optional) - Include all DOM elements (default: true)
• includeState (boolean, optional) - Include component state (default: false)

Response:

React Component Tree:

App (src/App.tsx:10:4)
└─ Button {variant="primary", size="large"} [role="button" name="Sign up"] (src/Button.tsx:42:5)
   └─ button [role="button" name="Sign up"]

Shows:

• React component hierarchy
• Props in JSX format (prop="value", prop={value})
• ARIA attributes ([role="..." name="..."])
• DOM elements with semantic roles (button, h1, p, img, etc.)
• Source locations (file:line:column)

---

take_snapshot

Get accessibility tree with element IDs

Arguments:

• verbose (boolean, optional) - Include all elements (default: false)

Response:

{
  "role": "RootWebArea",
  "name": "My App",
  "children": [
    {
      "role": "button",
      "name": "Sign up",
      "backendDOMNodeId": 48
    }
  ]
}

Use backendDOMNodeId with get_react_component_from_backend_node_id for detailed component inspection.

---

get_react_component_from_backend_node_id

Get React component details using backendDOMNodeId from snapshot

Arguments:

• backendDOMNodeId (number) - From take_snapshot

Response:

{
  "success": true,
  "component": {
    "name": "Button",
    "type": "ForwardRef",
    "source": {
      "fileName": "src/components/Button.tsx",
      "lineNumber": 42
    },
    "props": {"variant": "primary", "children": "Sign up"},
    "owners": [
      {"name": "OnboardingScreen", "source": {...}},
      {"name": "App", "source": {...}}
    ]
  }
}

Benefits:

• ✅ Fastest method for component lookup
• ✅ Returns complete owner chain (parent components)
• ✅ Precise source locations

Important: backendDOMNodeId is only valid within the same browser session.

---

Command-Line Options

# Auto-navigate on startup
TARGET_URL=http://localhost:3000 react-context-mcp

# Connect to existing Chrome with remote debugging
react-context-mcp --browserUrl http://localhost:9222

# Isolated mode (separate Chrome profile)
react-context-mcp --isolated --headless

# Custom Chrome executable
react-context-mcp --executablePath /path/to/chrome

# Set viewport size
react-context-mcp --viewport 1920x1080

Available flags:

• --headless - Run Chrome in headless mode
• --isolated - Use isolated user data directory
• --browserUrl <url> - Connect to existing Chrome debugging session
• --wsEndpoint <url> - WebSocket endpoint for CDP
• --executablePath <path> - Path to Chrome executable
• --channel <channel> - Chrome channel (stable, canary, beta, dev)
• --viewport <WxH> - Viewport size (e.g., 1280x720)

Troubleshooting

Browser Already Running

Use --isolated flag:

react-context-mcp --isolated

Missing Source Locations

• Requires development build
• Add Babel plugin (see Source Location Tracking section)
• Restart dev server after configuration changes

backendDOMNodeId Not Found

• Only valid within the same browser session
• Always use take_snapshot and get_react_component_from_backend_node_id in the same MCP session

Development & Publishing

Build

npm run build

Test Locally

# Test the built package
npm start

# Or with target URL
TARGET_URL=http://localhost:3000 npm start

Publish to npm

1. Update version in package.json:

   {
     "version": "0.2.0"
   }
   

2. Build and publish:

   npm run build
   npm publish
   

3. Verify publication:

   npm info react-context-mcp
   

Push to GitHub

# Commit all changes
git add .
git commit -m "feat: your feature description"

# Tag the version
git tag v0.2.0

# Push with tags
git push origin main --tags

License

Apache-2.0

Links

• npm Package: https://www.npmjs.com/package/react-context-mcp
• GitHub Repository: https://github.com/uxfreak/react-context-mcp
• Issues: https://github.com/uxfreak/react-context-mcp/issues
• Model Context Protocol: https://modelcontextprotocol.io