playbooks

home / mcp / mcp websocket server

MCP WebSocket Server

Provides mail operations over WebSocket with health checks and statistics for MCP clients.

Installation
Add the following to your MCP client configuration file.

Configuration

View docs
{
  "mcpServers": {
    "henrydyson-mcp-websocket-server": {
      "command": "node",
      "args": [
        "stdio-bridge.js",
        "wss://mcp-websocket-server.onrender.com/mcp"
      ],
      "env": {
        "PORT": "YOUR_PORT"
      }
    }
  }
}

This MCP WebSocket Server enables mail-related operations over a WebSocket connection. It lets you retrieve mail, search content, view statistics, and monitor health, while offering options to run locally or host remotely.

How to use

You connect your MCP client to the server via a WebSocket bridge. You can either use a deployed bridge that forwards to a remote WebSocket endpoint or run a local bridge that connects to your own WebSocket server. The bridge handles MCP protocol communication and exposes an endpoint for clients to interact with mail-related features.

How to install

Prerequisites: Node.js 16.0.0 or higher and npm are required to run and deploy the server.

Step 1: Install dependencies and build the project.

npm install
npm run build

Step 2: Start the server locally.

npm start

Additional notes and configuration

You have two configuration approaches for Claude Desktop to communicate with the MCP WebSocket Server.

Option 1: Use the deployed bridge (recommended). Configure Claude Desktop to connect to the remote MCP bridge via a standard JSON-based MCP server entry.

{
  "mcpServers": {
    "mail-mcp-server": {
      "command": "node",
      "args": [
        "stdio-bridge.js",
        "wss://mcp-websocket-server.onrender.com/mcp"
      ]
    }
  }
}

Option 2: Run a local bridge and point Claude Desktop at your local WebSocket endpoint.

{
  "mcpServers": {
    "mail-mcp-server": {
      "command": "node",
      "args": [
        "stdio-bridge.js",
        "ws://localhost:3000/mcp"
      ]
    }
  }
}

Deployment health and endpoints: you can access the health endpoint at /health and the MCP WebSocket endpoint at /mcp. The general web interface is available at the root path.

Troubleshooting

If you encounter errors like unexpected tokens in logs, ensure you are using the stdio-bridge.js file, verify the WebSocket URL is correct, and confirm the bridge process is running and reachable.

Tools and endpoints

The server provides these MCP operations: test_baglanti, mail_getir, mail_ara, and mail_istatistik. Use the MCP client to invoke these tools through the WebSocket bridge.

Available tools

test_baglanti

Test the connection to the MCP server to verify reachability and basic messaging.

mail_getir

Retrieve the latest mail for a specified email address.

mail_ara

Search within the content of mails to find matches for a query.

mail_istatistik

Show mail statistics such as counts and trends.