mcpField
W
ws-mcp

ws-mcp

Local
github.com/nick1udwigDeveloper Tools21Updated 62w ago
Repository

About ws-mcp

ws-mcp wraps MCP stdio servers with a WebSocket endpoint and is intended for use with kibitz. It runs the servers listed in a configuration file, which suits developers who need network access to local MCP servers.

Key features

  1. 01Wraps stdio MCP servers with WebSocket
  2. 02Manages multiple servers through a config file
  3. 03Default config includes wcgw and fetch
  4. 04Configurable port

Use cases

  1. 01Accessing local MCP servers over WebSocket
  2. 02Providing MCP servers as a backend for kibitz
  3. 03Launching multiple MCP servers quickly with uvx

MCP support

This project acts as a proxy that exposes stdio-based MCP servers to connected clients over WebSocket.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "ws": {
      "command": "uvx",
      "args": [
        "ws-mcp@latest"
      ]
    }
  }
}
Run commanduvx ws-mcp@latest

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
pypiws-mcp@latest

Tools

No tool list yet

Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.

Details

From the project README

ws-mcp

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

Quickstart

Prerequisites

Install uv:

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: 
    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:

uvx --refresh ws-mcp@latest

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

To use a config file and port:

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

Detailed Usage

# 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](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

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.