Browser-based MCP server running in Web Workers. Connect AI agents directly to your frontend application state.
npm install @mcp-fe/mcp-workerBrowser-based MCP server running in Web Workers. Connect AI agents directly to your frontend application state.
@mcp-fe/mcp-worker turns your browser into a queryable MCP server. It allows AI agents (like Claude) to:
- 🔍 Query user interactions in real-time
- 📊 Access application state directly
- 🎯 Register custom tools dynamically
- 💾 Store and retrieve events from IndexedDB
The MCP server runs in a Web Worker in your browser, requiring an MCP proxy server to bridge communication with AI agents.
This library runs an MCP server in your browser using Web Workers, exposing frontend application context to AI agents. This enables AI agents to query live browser state (DOM, localStorage, React state, etc.) through the standard MCP protocol.
The key advantage is making frontend context accessible to AI agents without custom backend code for each use case.
The library uses SharedWorker (preferred) or ServiceWorker (fallback):
- SharedWorker: Single instance shared across tabs, persistent connection
- ServiceWorker: Universal browser support, automatic fallback
Register custom MCP tools at runtime with handlers running in the main thread:
``typescript`
await workerClient.registerTool(
'get_user_data',
'Get current user information',
{ type: 'object', properties: {} },
async () => {
const user = getCurrentUser(); // Full browser access!
return {
content: [{ type: 'text', text: JSON.stringify(user) }]
};
}
);
Handlers have full access to:
- ✅ React context, hooks, state
- ✅ DOM API, localStorage
- ✅ All imports and dependencies
- ✅ Closures and external variables
`
Frontend App ←→ WorkerClient ←→ Web Worker ←→ WebSocket ←→ MCP Proxy ←→ AI Agent
↓
IndexedDB
1. Frontend App - Your application
2. WorkerClient - Simple API for worker communication
3. Web Worker - MCP server running in background
4. WebSocket - Real-time connection to proxy
5. MCP Proxy - Bridges browser with AI agents
6. AI Agent - Queries your app via MCP protocol
`bash`
npm install @mcp-fe/mcp-workeror
pnpm add @mcp-fe/mcp-worker
Copy worker scripts to your public directory:
`bash`
cp node_modules/@mcp-fe/mcp-worker/mcp-shared-worker.js public/
cp node_modules/@mcp-fe/mcp-worker/mcp-service-worker.js public/
`typescript
import { workerClient } from '@mcp-fe/mcp-worker';
await workerClient.init({
backendWsUrl: 'ws://localhost:3001' // Your MCP proxy URL
});
`
`typescript`
await workerClient.post('STORE_EVENT', {
event: {
type: 'click',
element: 'button',
elementText: 'Submit',
timestamp: Date.now()
}
});
`typescript`
await workerClient.registerTool(
'get_todos',
'Get all todos',
{ type: 'object', properties: {} },
async () => ({
content: [{ type: 'text', text: JSON.stringify(todos) }]
})
);
That's it! AI agents can now query your app via MCP protocol.
- Quick Start Guide - Complete guide to dynamic tool registration
- API Reference - Full API documentation
- Worker Details - Implementation details
- Architecture - How the proxy pattern works
- Initialization - Init queue handling
- Quick Start Examples - 4 simple examples
- Advanced Examples - Validation, async, error handling
- Examples Guide - How to use examples
- React Hooks Guide - React integration
- React Examples - Component examples
`typescript`
// Clicks, navigation, form inputs
await workerClient.post('STORE_EVENT', {
event: { type: 'click', element: 'button', ... }
});
`typescript`
await workerClient.registerTool('get_cart', 'Get shopping cart', ...,
async () => ({ content: [{ type: 'text', text: JSON.stringify(cart) }] })
);
`typescript`
const events = await workerClient.request('GET_EVENTS', {
type: 'navigation',
limit: 50
});
`typescript`
const connected = await workerClient.getConnectionStatus();
workerClient.onConnectionStatus((connected) => {
console.log('MCP connection:', connected);
});
The worker connects to an MCP proxy server that bridges browser with AI agents.
`bash`
docker pull ghcr.io/mcp-fe/mcp-fe/mcp-server:main
docker run -p 3001:3001 ghcr.io/mcp-fe/mcp-fe/mcp-server:main
Server available at ws://localhost:3001
`bash`
git clone https://github.com/mcp-fe/mcp-fe.git
cd mcp-fe
pnpm install
nx serve mcp-server
See mcp-server docs for complete setup.
Register custom MCP tools at runtime:
`typescript`
await workerClient.registerTool(
'get_user_data',
'Get current user information',
{ type: 'object', properties: {} },
async () => {
const user = getCurrentUser(); // Full browser access!
return {
content: [{
type: 'text',
text: JSON.stringify(user)
}]
};
}
);
Learn more:
- Guide - Complete step-by-step guide
- Quick Start Examples - Ready-to-use examples
- Advanced Examples - Validation, async, error handling
- React Integration - React hooks
Store and query user interactions:
`typescript
// Store event
await workerClient.post('STORE_EVENT', {
event: { type: 'click', element: 'button', ... }
});
// Query events
const events = await workerClient.request('GET_EVENTS', {
type: 'click',
limit: 10
});
`
Monitor MCP proxy connection:
`typescript`
const connected = await workerClient.getConnectionStatus();
workerClient.onConnectionStatus((connected) => {
console.log('Status:', connected);
});
- ✅ Chrome/Chromium 80+ - Full support
- ✅ Firefox 78+ - Full support
- ✅ Safari 16.4+ - Full support
- ✅ Edge 80+ - Full support (Chromium-based)
Requirements: ES2020+, WebWorker, IndexedDB, WebSocket
See Worker Details for more information.
Ensure worker files are in your public directory and paths match:
`typescript``
await workerClient.init({
sharedWorkerUrl: '/path/to/mcp-shared-worker.js',
serviceWorkerUrl: '/path/to/mcp-service-worker.js'
});
1. Verify MCP proxy server is running
2. Check WebSocket connection in DevTools Network tab
3. Verify CORS settings if on different origin
SharedWorker requires HTTPS in production and may be blocked in incognito mode. The library automatically falls back to ServiceWorker.
For more help: See Worker Details
- Main MCP-FE Project - Complete documentation
- @mcp-fe/event-tracker - Framework-agnostic event tracking
- @mcp-fe/react-event-tracker - React integration hooks
Licensed under the Apache License, Version 2.0. See LICENSE for details.
---
For most applications, consider using @mcp-fe/react-event-tracker for a more convenient React-focused API.