mcp2websocket

library2.0.0jsnpmunverified

mcp2websocket v2.0.0 bridges MCP stdio clients to WebSocket-based MCP servers, translating JSON-RPC messages between the two transports. It provides automatic reconnection with exponential backoff, message queuing during disconnects, heartbeat/ping-pong for health checks, and optional debug logging to stderr. Unlike raw WebSocket clients, it handles the full lifecycle: graceful shutdown, connection management, and compatibility with MCP client configs (e.g., Claude Desktop). Requires Node >=14. Package is stable with infrequent releases.

devops

npm install mcp2websocket

package ↗

INSTALL

IMPORT

SIG · MCP2WEBSOCKET

mcp2websocket

devopsjavascriptv2.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import mcp2websocket from 'mcp2websocket'

✗ const mcp2websocket = require('mcp2websocket')

Package is ESM-only; CommonJS require will fail with ERR_REQUIRE_ESM.

mcp2websocket (binary)

✓ npx mcp2websocket ws://example.com/mcp

✗ npx mcp2websocket --url ws://example.com/mcp

The URL is a positional argument, not an --url flag. Use short options -t and -d for token and debug.

default via require

✓ const mcp2websocket = (await import('mcp2websocket')).default

✗ const mcp2websocket = require('mcp2websocket')

Only dynamic import works from CommonJS; static require throws ERR_REQUIRE_ESM.

Initializes a bridge from stdio to a WebSocket MCP server with authentication and debug flags, including graceful shutdown.

import mcp2websocket from 'mcp2websocket'; async function main() { // Bridge to a WebSocket MCP server const bridge = await mcp2websocket('wss://mcp.example.com', { token: process.env.AUTH_TOKEN ?? '', debug: process.env.DEBUG === 'true', }); // The bridge connects stdin/stdout to the WebSocket // Messages flow automatically — no further API calls needed // Graceful shutdown on SIGINT/SIGTERM process.on('SIGINT', () => bridge.close()); process.on('SIGTERM', () => bridge.close()); } main().catch(console.error);

Debug

Known issues

gotchaThe package is ESM-only; require() will not work. Use dynamic import or ensure your project is ESM.

fix

Add "type": "module" to package.json or use dynamic import: const pkg = await import('mcp2websocket')

affects: >=1.0.0

gotchaThe WebSocket URL must be the first positional argument; do not use --url or similar flags.

fix

Run as: mcp2websocket ws://example.com/mcp

affects: all

gotchaDebug logs go to stderr; do not rely on stdout for debugging or you will corrupt the MCP protocol.

fix

Use --debug flag or DEBUG=true env var; logs appear on stderr only.

affects: all

gotchaToken authentication only works via --token flag or AUTH_TOKEN env var; no programmatic token setting in CLI mode.

fix

Pass --token your-token or set AUTH_TOKEN environment variable.

affects: all

gotchaMessage queuing only occurs during disconnection; if queue grows unbounded, memory pressure may occur.

fix

Monitor memory usage; consider implementing backpressure in your MCP client if messages are produced faster than the server can consume.

affects: all

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/mcp2websocket/src/index.js from /path/to/your/file.js not supported.

Using CommonJS require() to load an ESM package.

fix

Switch to ESM: set "type": "module" in package.json, rename .js to .mjs, or use dynamic import: const pkg = await import('mcp2websocket')

Error: invalid or unexpected token at line 1, column 1 when receiving messages

Debug output has been accidentally redirected to stdout, which interferes with MCP JSON-RPC messages.

fix

Ensure --debug flag or DEBUG env var is not set when running in production; logs only appear on stderr.

SyntaxError: Unexpected token '}' at JSON.parse

MCP server sent malformed JSON-RPC message over WebSocket.

fix

Validate that the server sends valid JSON-RPC messages (must contain jsonrpc, id, method, etc.). Check WebSocket server logs.

WebSocket connection to 'ws://...' failed: Error: connect ECONNREFUSED

The WebSocket server is not running or unreachable.

fix

Verify the WebSocket server is started and reachable at the given URL. Check firewall/network settings.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

wsoptionalWebSocket client for Node.js

Agent activity

3 hits · last 30 days

node

Amazon

Resources

packagemcp2websocket ↗