WebSocket Wrapper MCP Server

WebSocket MCP Wrapper (ws-mcp) is a utility that wraps Model Context Protocol (MCP) stdio servers with a WebSocket interface. This tool is particularly useful for integrating MCP servers with web applications like Kibitz that require WebSocket communication. The wrapper allows you to run multiple MCP servers simultaneously through a single WebSocket endpoint, making it easier to manage and interact with various tools like file management, HTTP requests, and search capabilities from web-based interfaces.

Installation

To use the WebSocket MCP Wrapper, you'll need to have uv installed on your system:

curl -LsSf https://astral.sh/uv/install.sh | sh

Once uv is installed, you can install and run ws-mcp using the following command:

uvx --refresh ws-mcp@latest

This will start all configured servers on the default port (10125).

Configuration

The WebSocket MCP Wrapper can be configured in two ways:

1. Using a Configuration File

The default configuration includes:

wcgw: For general system operations and file management
fetch: For making HTTP requests

To create a custom configuration:

Create a configuration file based on the sample:
```
cp sample.config.json config.json
```
Modify config.json to add or remove servers based on your needs.

Run with the custom config:

uvx --refresh ws-mcp@latest --config path/to/config.json --port 10125

2. Using Command-Line Arguments

You can also specify servers directly via command-line arguments:

# Run a single server
uvx --refresh ws-mcp --command "uvx mcp-server-fetch" --port 3002

# Run multiple servers
uvx --refresh ws-mcp --command "uvx mcp-server-fetch" --command "uvx --from wcgw@latest --python 3.12 wcgw_mcp" --port 3004

Environment Variables

For servers that require environment variables:

# Using environment variables directly
export BRAVE_API_KEY=YOUR_API_KEY_HERE
uvx --refresh ws-mcp --env BRAVE_API_KEY=$BRAVE_API_KEY --command "npx -y @modelcontextprotocol/server-brave-search" --port 3003

# Using an .env file
uvx --refresh ws-mcp --env-file path/to/.env --command "npx -y @modelcontextprotocol/server-brave-search" --port 3003

Usage with Different MCP Servers

Using with wcgw (File Management)

# On macOS
uvx --refresh ws-mcp --command "uvx --from wcgw@latest --python 3.12 wcgw_mcp" --port 3001

# On Linux (or if you have issues on macOS)
cd /tmp
git clone https://github.com/nick1udwig/wcgw.git
cd wcgw
git submodule update --init --recursive
git checkout hf/fix-wcgw-on-ubuntu
cd ..
uvx --refresh ws-mcp --command "uvx --from /tmp/wcgw --with /tmp/wcgw/src/mcp_wcgw --python 3.12 wcgw_mcp" --port 3001

Using with Fetch (HTTP Requests)

uvx --refresh ws-mcp --command "uvx mcp-server-fetch" --port 3002

Using with Brave Search

export BRAVE_API_KEY=YOUR_API_KEY_HERE
uvx --refresh ws-mcp --env BRAVE_API_KEY=$BRAVE_API_KEY --command "npx -y @modelcontextprotocol/server-brave-search" --port 3003

Connecting to the WebSocket

Once the WebSocket MCP Wrapper is running, you can connect to it using WebSocket clients or integrate it with applications like Kibitz that support WebSocket communication with MCP servers.