MSW MCP Server

A Model Context Protocol (MCP) server that enables AI-driven control of Mock Service Worker (MSW) in browser environments. This server acts as a bridge between AI assistants and MSW service workers, allowing dynamic API mocking through intelligent handler generation and real-time updates.

Demo

https://github.com/user-attachments/assets/06959759-b198-4cd1-ae2b-11ede32acd8e

Key Features

• 🤖 AI-powered mock generation - Generate MSW handlers from natural language
• ⚡ Real-time updates - Modify API mocks without reloading the page
• 🌉 WebSocket bridge - Seamless communication between AI and browser
• 🛠️ Automated setup - Use /msw-setup prompt for instant project scaffolding

Architecture

┌─────────────────┐    MCP Protocol    ┌─────────────────────┐    WebSocket    ┌──────────────────┐
│                 │◄──────────────────►│                     │◄───────────────►│                  │
│   AI Assistant  │                    │   MSW MCP Server    │                 │  Browser MSW     │
│   (Claude etc.) │                    │                     │                 │  Service Worker  │
│                 │                    │                     │                 │                  │
└─────────────────┘                    └─────────────────────┘                 └──────────────────┘

Getting Started

Installation

Standard configuration (works with most MCP clients):

{
  "mcpServers": {
    "msw-mcp": {
      "command": "npx",
      "args": ["msw-mcp@latest"]
    }
  }
}

Quick install links for vscode:

Claude Code:

Use the Claude Code CLI to add the MSW MCP server:

claude mcp add msw-mcp npx msw-mcp@latest

Also supports: Cursor, Gemini-cli, Windsurf, Cline, Roo Cline, and other MCP-compatible clients.

Quick Setup

Use the /msw-setup prompt in your MCP client to automatically configure your project:

/msw-setup

This will:

• Auto-detect your framework (React, Vue, Svelte, etc.)
• Install required dependencies (msw and msw-mcp)
• Create the complete mocks directory structure
• Configure environment variables
• Integrate with your app entry point

If you prefer manual configuration:

# Install dependencies
npm install -D msw msw-mcp

# Initialize MSW service worker
npx msw init public/ --save

Create mocks/index.js:

import { enableMocking } from 'msw-mcp/client';
import { setupWorker } from 'msw/browser';

const worker = setupWorker();

export async function initMocks() {
  if (process.env.NODE_ENV !== 'development') return;

  await enableMocking({
    worker,
    wsEnabled: true,
    wsBridgeOptions: {
      url: 'ws://localhost:6789',
    },
  });
}

Import in your app entry:

import { initMocks } from './mocks';

initMocks().then(() => {
  // Start your app
});

MCP Tools

msw_add_handlers

Add new request handlers dynamically:

// Example usage from AI
'Create a GET /users endpoint that returns a list of users';
// Generates: http.get('/users', () => HttpResponse.json([...]))

msw_get_status

Check current MSW status and active handlers.

msw_update_handlers

Update existing handlers by URL pattern and optional HTTP methods (e.g., methods: ['GET', 'POST']).

msw_remove_handlers

Remove handlers by URL pattern and optional HTTP methods (e.g., methods: ['GET'] to remove only GET handlers).

msw_reset_handlers

Reset all handlers to initial state.

See DOCUMENTATION.md for detailed API reference.

Configuration

Server Arguments

• --mock-ws-port=<port> - WebSocket server port (default: 6789)
• --persist-handlers - Save handlers across page refreshes (or --persist-handlers=10 persists only 10 most recent handlers)
• --single-client - Only broadcast to the most recent tab

Environment Variables for client bridge

Since they are just envs used in the generated setup code, you can customize them as needed.

Create .env.local:

ENABLE_MSW_MOCK=true
ENABLE_MSW_WS_MOCK=true
MCP_SERVER_URL=ws://localhost:6789

Usage Examples

Generate a REST API:

"Create a REST API for user management with CRUD operations"

Mock external APIs:

"Mock the GitHub API to return fake repository data"

Test error scenarios:

"Make the /users endpoint return a 500 error"

Development

npm run build     # Build TypeScript
npm run dev       # Build and run
npm run start     # Run built server

Documentation

For detailed documentation including:

• Complete API reference
• WebSocket protocol details
• Advanced configuration options
• Frontend integration guide
• Debugging tips

See DOCUMENTATION.md

Contributing

Contributions are welcome! Please see DOCUMENTATION.md for detailed development information.

License

MIT License

Related Projects

• Model Context Protocol - Protocol specification
• Mock Service Worker - API mocking library