wsrx-mcp

English | 简体中文

An MCP (Model Context Protocol) server that manages WebSocket Reflector X (wsrx) tunnels.

The ret2shell CTF platform exposes dynamic challenge instances only through WebSocket traffic links such as:

wss://ctf.example.com/api/traffic/<token>?port=9999

Platforms that hand out plain host:port pairs can be reached with nc / pwntools directly; these links cannot.

wsrx bridges a WebSocket endpoint to a local TCP port; wsrx-mcp then wraps starting, inspecting, and closing tunnels as MCP tools, so your MCP client (Claude Desktop, Codex, etc.) can call them directly — no manual terminal work.

┌───────────────┐   TCP    ┌──────────────┐   WSS    ┌───────────────────┐
│ nc / pwntools ├─────────►│ wsrx connect ├─────────►│ platform instance │
└───────────────┘  :1337   └──────────────┘ wss link └───────────────────┘
                     managed by wsrx-mcp (MCP tools)

Tools

Related MCP server: ptywright

Requirements

• Python 3.10+

• The wsrx CLI (releases) installed and on PATH, or set WSRX_BINARY to its location.

Install & configure

Run directly from GitHub with uvx (recommended — no clone needed):

{
  "mcpServers": {
    "wsrx": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/springbot2025/wsrx-mcp", "wsrx-mcp"]
    }
  }
}

Or install once, then point your MCP client at the wsrx-mcp command:

pipx install git+https://github.com/springbot2025/wsrx-mcp

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

Configuration (environment variables)

Example session

Ask your agent:

Connect to wss://ctf.example.com/api/traffic/abc123?port=9999 (the wsrx link from the ret2shell platform) and tell me the local endpoint.

The agent calls wsrx_connect, gets back {"endpoint": "127.0.0.1:54321", ...}, and can then run nc 127.0.0.1 54321 or use pwntools to connect. The same tunnel is reused across calls, and all tunnels close when the service exits.

Security notes

• Tunnels bind to 127.0.0.1 by default.

• The server manages subprocesses and holds no credentials — traffic tokens live in the URLs you pass in.

• Only ws:// and wss:// remotes are accepted.

Development

pip install -e . pytest
pytest

The tunnel core (wsrx_mcp.manager) has no MCP dependency and is fully injectable for testing.

License

MIT