ws-mcp

CategoryWeb
AuthorCommunity
Stars184
PricingFree

Overview

ws-mcp solves a critical connectivity gap for developers who need to expose Model Context Protocol (MCP) servers over a network rather than relying on local stdio transport. By wrapping MCP servers in a WebSocket layer, it enables remote LLM clients and specialized interfaces—like Kibitz—to interact with your tools and resources across different machines or containers. This is particularly useful for team-based AI workflows or deploying MCP servers to cloud environments where a persistent socket connection is required. Instead of rewriting your server logic, you can simply use this wrapper to bridge your existing MCP implementation to a web-accessible endpoint, simplifying the integration between your backend tools and remote AI agents.

Highlights

  • Converts stdio MCP servers to WebSocket transport
  • Enables remote access for cloud-hosted AI tools
  • Seamless integration with the Kibitz client
  • Eliminates the need for local-only server execution
  • Lightweight wrapper for existing MCP implementations

Full Documentation

ws-mcp

Wrap MCP stdio servers with a WebSocket.
For use with kibitz.

Quickstart

Prerequisites

Install uv:

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

Configuration

The config file specifies which MCP servers to run.
The default config (no --config or --command args provided) includes:

  • wcgw: For general system operations and file management

  • fetch: For making HTTP requests

To make a configuration file:

1. Create your configuration file:

bash
cp sample.config.json config.json

2. Modify config.json to add or remove servers based on your needs.
3. Run with --config path/to/config.json to use the new config file.

Running ws-mcp

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

bash
uvx --refresh ws-mcp@latest

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

To use a config file and port:

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

Detailed Usage

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

Example using wcgw

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

Example 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

Or, with a .env file:

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

--command can be supplied multiple times!


 Example serving multiple servers at once:

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

uvx --refresh ws-mcp --env-file path/to/.env --config path/to/config.json --port 3005
View official source
Join our Telegram