ws-mcp is a versatile MCP solution that acts as a WebSocket wrapper for MCP stdio servers, designed to enhance the connectivity and accessibility of AI models. It streamlines the integration of various MCP servers, such as wcgw for system operations and fetch for HTTP requests, by enabling communication over WebSockets. This eliminates the complexities associated with managing multiple stdio connections.

Developers can easily configure and run multiple MCP servers simultaneously, either through a configuration file or directly via command-line arguments. ws-mcp simplifies deployment and management, allowing AI models to seamlessly interact with external data sources and services. By providing a unified WebSocket interface, ws-mcp significantly improves the efficiency and flexibility of AI model integration within the MCP ecosystem. It supports environment variables and .env files for secure API key management.

WebSocket Wrapping for MCP

ws-mcp acts as a bridge, wrapping existing MCP stdio servers within a WebSocket interface. This allows MCP servers, which typically communicate via standard input/output streams, to be accessed and interacted with over a WebSocket connection. This is particularly useful in scenarios where direct stdio access is not feasible, such as web-based applications or remote server environments. The core functionality involves receiving data over the WebSocket, forwarding it to the underlying MCP server via stdio, and then transmitting the server's response back to the client through the same WebSocket connection. This wrapping provides a standardized and network-friendly way to interact with diverse MCP servers.

Use Case: Imagine a web application needing to access a file system MCP server (like wcgw) running on a remote machine. Instead of complex SSH tunneling or other workarounds, ws-mcp can wrap the wcgw server. The web application then connects to ws-mcp via WebSocket, sending file system commands. ws-mcp relays these commands to wcgw, receives the results, and sends them back to the web application over the WebSocket.

Configuration-Driven Server Management

ws-mcp utilizes a configuration file (typically in JSON format) to define and manage the MCP servers it wraps. This configuration specifies which MCP servers to run, along with any necessary parameters or environment variables. By using a configuration file, ws-mcp enables dynamic and flexible server deployment. Administrators can easily add, remove, or modify the MCP servers being served without altering the core ws-mcp application code. This approach promotes modularity and simplifies the management of complex MCP ecosystems. The configuration file adheres to the standard MCP format, ensuring compatibility and ease of integration with other MCP tools.

Use Case: An organization might have several MCP servers, such as one for fetching data from the web (fetch), one for interacting with a database, and another for performing specific AI tasks. A single configuration file can define all these servers, allowing ws-mcp to launch and manage them simultaneously. This simplifies deployment and ensures that all necessary MCP servers are readily available.

Multi-Server Support

ws-mcp can serve multiple MCP servers concurrently on a single port. This is achieved by multiplexing the WebSocket connections and routing requests to the appropriate underlying MCP server based on the configuration. This capability significantly improves resource utilization and simplifies deployment, as multiple functionalities can be exposed through a single endpoint. The ability to serve multiple servers is configured either through a configuration file or by specifying multiple --command arguments when launching ws-mcp.

Use Case: A developer might want to expose both a search server (e.g., Brave Search) and a general utility server (e.g., wcgw) through a single ws-mcp instance. By configuring ws-mcp to run both servers, clients can access both functionalities via the same WebSocket endpoint, simplifying client-side integration.

Integration Advantages

ws-mcp leverages standard tools like uvx for execution and management, simplifying deployment and ensuring compatibility across different environments. It supports environment variables and .env files for secure configuration, allowing sensitive information like API keys to be managed separately from the main configuration. The use of WebSockets enables seamless integration with web-based applications and other systems that require real-time, bidirectional communication. This makes ws-mcp a versatile solution for bridging the gap between traditional MCP servers and modern application architectures.