Ws MCP

ws-mcp is a tool that encapsulates MCP standard input-output servers as WebSockets, mainly used in conjunction with kibitz and supports managing multiple MCP services through a configuration file.

Developer tools Research and data #WebSocket encapsulation #MCP services #Multi-service management #Development tools .Python

rating : 2.5 points

downloads : 49

update time : 2025-04-28

What is ws-mcp?

ws-mcp is a tool that converts MCP (Model Context Protocol) standard input-output servers into WebSocket services. It allows you to interact with various MCP servers via the WebSocket protocol, especially suitable for use with front-end tools like kibitz.

How to use ws-mcp?

You can start ws-mcp through a simple command line. It will automatically run the MCP servers specified in the configuration file and expose them as WebSocket endpoints.

Applicable scenarios

When you need to integrate MCP server functions into a front-end application or access MCP services across the network, ws-mcp is an ideal choice.

Main features

Multi-server supportIt can run and wrap multiple MCP servers simultaneously, with each server having an independent WebSocket endpoint.

Flexible configurationIt supports specifying the MCP servers to run through a configuration file or command-line parameters.

Environment variable supportYou can pass environment variables to the MCP server through a.env file or the command line.

Advantages and limitations

Advantages

Simplifies the integration of MCP servers in front-end applications

Supports the simultaneous operation of multiple MCP servers

Flexible configuration and easy to expand

Limitations

Requires the pre-installation of the uv toolchain

Some MCP servers may have specific platform requirements

WebSocket connections require additional error handling and reconnection

How to use

Install the uv tool

First, you need to install the uv toolchain, which is a prerequisite for running ws-mcp.

Prepare the configuration file

Copy the sample configuration file and modify it as needed, adding or removing the required MCP servers.

Run ws-mcp

Use the uvx command to start ws-mcp, and you can specify the configuration file and port.

Usage examples

Integrate file management functionalityProvide file system operation capabilities through the wcgw server

Add HTTP request capabilitiesProvide HTTP request functionality through the fetch server

Integrate Brave searchProvide web search functionality through the Brave search server

Frequently Asked Questions

How to run wcgw on Linux?

Can multiple MCP servers be run simultaneously?

How to pass environment variables to the MCP server?

Related resources

uv tool documentation

uv installation and usage guide

kibitz project

A front-end tool used in conjunction with ws-mcp

MCP protocol specification

Official documentation for the Model Context Protocol

🚀 ws-mcp

Wrap MCP standard input-output servers into WebSocket, suitable for kibitz.

🚀 Quick Start

Prerequisites

Install uv:

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

Configuration

The configuration file specifies which MCP servers to run. If neither the --config nor the --command parameter is provided, the default configuration includes:

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

How to create a configuration file:

Copy the example configuration file:
```
cp sample.config.json config.json
```
Modify config.json to add or remove servers as needed.
Run the new configuration file using --config path/to/config.json.

Running ws-mcp

Basic usage with the default configuration file (no --config or --command provided) and port:

uvx --refresh ws-mcp@latest

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

Using a configuration file and port:

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

📚 Documentation

# Example of using fetch
uvx --refresh ws-mcp --command "uvx mcp-server-fetch" --port 3002

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

## On Linux (or when encountering 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

# Example of using 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

# Alternatively, use a .env file:
uvx --refresh ws-mcp --env-file path/to/.env --command "npx -y @modelcontextprotocol/server-brave-search" --port 3003

# The `--command` can be provided multiple times!
# Example of serving multiple servers simultaneously:
uvx --refresh ws-mcp --env-file path/to/.env --command "npx -y @modelcontextprotocol/server-brave-search" --command "uvx mcp-server-fetch" --port 3004

# Servers can also be specified in a `.json` file following the [standard MCP format](https://modelcontextprotocol.io/quickstart/user#2-add-the-filesystem-mcp-server)
uvx --refresh ws-mcp --env-file path/to/.env --config path/to/config.json --port 3005