websocat-mcp

An MCP (Model Context Protocol) server for WebSocket operations, providing tools to connect, send, receive, and manage WebSocket connections.

Installation

From GitHub

git clone https://github.com/shivam-jainn/websocat-mcp.git
cd websocat-mcp
bun install
bun run build

From npm (when published)

npm install -g websocat-mcp

Or locally:

npm install websocat-mcp

Build

bun run build

Usage

This MCP server provides the following tools:

websocket_connect

Connect to a WebSocket server.

Parameters:

• url (required): WebSocket URL (e.g., ws://localhost:8080 or wss://example.com)
• connectionId (optional): Unique identifier for this connection (auto-generated if not provided)

Example:

{
  "url": "ws://localhost:8080",
  "connectionId": "my-connection"
}

websocket_send

Send a message through a WebSocket connection.

Parameters:

• connectionId (required): Connection ID to send the message through
• message (required): Message to send

Example:

{
  "connectionId": "my-connection",
  "message": "Hello, WebSocket!"
}

websocket_receive

Receive messages from a WebSocket connection (waits for messages).

Parameters:

• connectionId (required): Connection ID to receive messages from
• timeout (optional): Timeout in milliseconds (default: 5000)
• maxMessages (optional): Maximum number of messages to receive (default: 1)

Example:

{
  "connectionId": "my-connection",
  "timeout": 10000,
  "maxMessages": 5
}

websocket_close

Close a WebSocket connection.

Parameters:

• connectionId (required): Connection ID to close
• code (optional): Close code (default: 1000)
• reason (optional): Close reason

Example:

{
  "connectionId": "my-connection",
  "code": 1000,
  "reason": "Done"
}

websocket_list

List all active WebSocket connections.

Parameters: None

websocket_create_server

Create a WebSocket server.

Parameters:

• port (optional): Port to listen on (default: 8080)
• hostname (optional): Hostname to bind to (default: localhost)

Example:

{
  "port": 8080,
  "hostname": "localhost"
}

MCP Configuration

To use this MCP server with Cursor or other MCP clients, add it to your MCP configuration:

Local Installation

{
  "mcpServers": {
    "websocat-mcp": {
      "command": "bun",
      "args": ["/path/to/websocat-mcp/build/index.js"]
    }
  }
}

Global Installation (npm)

{
  "mcpServers": {
    "websocat-mcp": {
      "command": "websocat-mcp"
    }
  }
}

Using bunx (no installation needed)

{
  "mcpServers": {
    "websocat-mcp": {
      "command": "bunx",
      "args": ["--bun", "websocat-mcp"]
    }
  }
}

Features

• ✅ Connect to WebSocket servers
• ✅ Send messages through WebSocket connections
• ✅ Receive messages with timeout support
• ✅ Close connections gracefully
• ✅ List all active connections
• ✅ Create WebSocket servers
• ✅ Connection state management
• ✅ Error handling

Development

This project uses:

• Bun - Fast JavaScript runtime
• Model Context Protocol SDK - MCP server implementation
• TypeScript - Type safety

License

MIT