Wrap MCP stdio servers with a WebSocket.
https://github.com/nick1udwig/ws-mcpStop wrestling with stdio pipes when you need to integrate MCP servers into web applications or distributed systems. ws-mcp wraps any MCP stdio server with a clean WebSocket interface, letting you access powerful MCP capabilities over the network.
MCP servers run as stdio processes by design, which works great for desktop applications but creates friction when you're building:
ws-mcp solves this by providing a WebSocket wrapper around any MCP stdio server. Instead of managing subprocess pipes and stdio streams, you get a standard WebSocket endpoint that speaks MCP protocol.
# Turn any MCP server into a WebSocket service
uvx --refresh ws-mcp@latest --command "uvx mcp-server-fetch" --port 3002
# Now connect via WebSocket instead of stdio
ws://localhost:3002/mcp
Run multiple MCP servers through one WebSocket connection - perfect for complex workflows that need different capabilities:
# Combine file operations, HTTP requests, and search in one endpoint
uvx --refresh ws-mcp \
--command "uvx --from wcgw@latest --python 3.12 wcgw_mcp" \
--command "uvx mcp-server-fetch" \
--command "npx -y @modelcontextprotocol/server-brave-search" \
--port 3004
Your client connects to one WebSocket and gets access to file system operations, HTTP requests, and web search through the same interface.
Define your MCP server stack in JSON and deploy consistently across environments:
{
"servers": {
"filesystem": {
"command": "uvx",
"args": ["--from", "wcgw@latest", "--python", "3.12", "wcgw_mcp"]
},
"web-fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"]
},
"search": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-brave-search"],
"env": {"BRAVE_API_KEY": "your-key-here"}
}
}
}
uvx --refresh ws-mcp --config production-config.json --port 3005
Web Application Backend: Your React app needs to perform file operations and make external API requests. Instead of building custom endpoints, connect directly to ws-mcp and use existing MCP servers.
Development Tools: Build browser-based developer tools that need system access. Connect your web interface to ws-mcp running locally for seamless file operations and system commands.
Multi-User Environments: Deploy ws-mcp in containers or serverless functions. Each user gets their own MCP server instance accessible via WebSocket, with proper environment isolation.
API Gateway Integration: Use ws-mcp as a microservice that translates between HTTP/REST and MCP protocols. Your existing API infrastructure can now consume MCP capabilities.
Get started immediately with sensible defaults:
# Starts with wcgw (file ops) and fetch (HTTP) servers
uvx --refresh ws-mcp@latest
# → WebSocket available at ws://localhost:10125
Pass secrets and configuration cleanly to your MCP servers:
# Individual environment variables
export BRAVE_API_KEY=your-key
uvx --refresh ws-mcp --env BRAVE_API_KEY=$BRAVE_API_KEY --command "npx -y @modelcontextprotocol/server-brave-search"
# Or use .env files for complex configurations
uvx --refresh ws-mcp --env-file .env --config servers.json
Instead of this complexity:
# Managing stdio subprocesses directly
import subprocess
import json
proc = subprocess.Popen(['uvx', 'mcp-server-fetch'],
stdin=subprocess.PIPE,
stdout=subprocess.PIPE)
# ... handle stdio protocol, process management, error handling
You get this simplicity:
// Clean WebSocket integration
const ws = new WebSocket('ws://localhost:3002');
ws.send(JSON.stringify({
type: 'tool_call',
tool: 'fetch',
args: { url: 'https://api.example.com/data' }
}));
ws-mcp handles the stdio complexity, process lifecycle, and protocol translation so you can focus on building features instead of managing infrastructure.