ws-mcp

ws-mcp

WebSocket bridge for MCP stdio servers.

19
Stars
7
Forks
19
Watchers
1
Issues
ws-mcp wraps Model Context Protocol (MCP) stdio servers with a WebSocket interface, enabling seamless integration with web-based clients and tools. It allows users to configure and launch multiple MCP servers via a flexible configuration file or command-line arguments. The tool is designed to be compatible with services such as wcgw, fetch, and other MCP-compliant servers, providing standardized access to system operations, HTTP requests, and more. Integration with tools like Kibitz enables broader applications in model interaction workflows.

Key Features

Wraps MCP stdio servers with a WebSocket interface
Supports multiple server instances concurrently
Flexible configuration via JSON files
Command-line control for server selection and setup
Environment variable management via CLI or .env files
Integration with common MCP servers like wcgw and fetch
Custom port selection
Support for 3rd party MCP servers
Designed for compatibility with Kibitz
Simple installation and quickstart process

Use Cases

Enabling web-based interaction with MCP-compliant servers
Managing and orchestrating multiple context servers across different tasks
Providing standardized system operations through a WebSocket API
Remote execution of commands and workflows for system administration
Facilitating HTTP requests and data retrieval via fetch server in web clients
Integrating with third-party search APIs such as Brave Search
Dynamic deployment and configuration of model context servers
Secure remote file management over WebSocket
Rapid prototyping and testing of multi-server MCP environments
Supporting AI workflows that require external tools through standardized interfaces

README

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

Star History

Star History Chart

Repository Owner

nick1udwig
nick1udwig

User

Repository Details

Language Python
Default Branch master
Size 51 KB
Contributors 2
MCP Verified Nov 12, 2025

Programming Languages

Python
100%

Tags

Join Our Newsletter

Stay updated with the latest AI tools, news, and offers by subscribing to our weekly newsletter.

We respect your privacy. Unsubscribe at any time.

Related MCPs

Discover similar Model Context Protocol servers

  • kibitz

    kibitz

    The coding agent for professionals with MCP integration.

    kibitz is a coding agent that supports advanced AI collaboration by enabling seamless integration with Model Context Protocol (MCP) servers via WebSockets. It allows users to configure Anthropic API keys, system prompts, and custom context providers for each project, enhancing contextual understanding for coding tasks. The platform is designed for developers and professionals seeking tailored AI-driven coding workflows and provides flexible project-specific configuration.

    • 104
    • MCP
    • nick1udwig/kibitz
  • MCP Manager for Claude Desktop

    MCP Manager for Claude Desktop

    A desktop app to manage Model Context Protocol (MCP) servers for Claude Desktop on MacOS.

    MCP Manager for Claude Desktop provides a user-friendly interface to manage Model Context Protocol (MCP) servers, enabling Claude to access private data, APIs, and local or remote services securely from a MacOS desktop. It facilitates rapid configuration and integration with a wide variety of MCP servers, including productivity tools, databases, and web APIs. The app runs locally to ensure data privacy and streamlines connecting Claude to new sources through simple environment and server settings management.

    • 270
    • MCP
    • zueai/mcp-manager
  • books-mcp-server

    books-mcp-server

    A server implementation supporting Model Context Protocol integration with cherry-studio.

    books-mcp-server allows users to set up a Model Context Protocol (MCP) compliant server for managing and interacting with AI models. It enables integration with cherry-studio through STDIO commands and structured server configurations. The tool provides straightforward setup instructions and supports launching the server with customizable parameters, making it suitable for various AI context management tasks.

    • 5
    • MCP
    • VmLia/books-mcp-server
  • YAMCP

    YAMCP

    Unified management and orchestration of Model Context Protocol servers via a local gateway workspace.

    YAMCP is a command-line tool that enables organizing and managing multiple MCP (Model Context Protocol) servers as unified workspaces. It allows users to connect to various local or remote MCP servers, group them by functionality or application, and expose them as a single MCP server gateway for AI applications. The tool simplifies monitoring and debugging by centralizing server communication logs and provides workspace management and runtime control. YAMCP facilitates seamless integration with AI applications by providing a consolidated configuration and context management interface.

    • 57
    • MCP
    • hamidra/yamcp
  • mcpmcp-server

    mcpmcp-server

    Seamlessly discover, set up, and integrate MCP servers with AI clients.

    mcpmcp-server enables users to discover, configure, and connect MCP servers with preferred clients, optimizing AI integration into daily workflows. It supports streamlined setup via JSON configuration, ensuring compatibility with various platforms such as Claude Desktop on macOS. The project simplifies the connection process between AI clients and remote Model Context Protocol servers. Users are directed to an associated homepage for further platform-specific guidance.

    • 17
    • MCP
    • glenngillen/mcpmcp-server
  • WebSearch-MCP

    WebSearch-MCP

    Real-time web search for AI assistants via Model Context Protocol.

    WebSearch-MCP is a Model Context Protocol (MCP) server that enables real-time web search capabilities for AI assistants through the stdio transport. It connects with a web crawler API to retrieve up-to-date search results and serves these results to AI models like Claude. The solution offers straightforward configuration and seamless integration with various MCP clients, enhancing AI model access to current and relevant external information.

    • 19
    • MCP
    • mnhlt/WebSearch-MCP
  • Didn't find tool you were looking for?

    Be as detailed as possible for better results