Skip to content
springbot2025Public

About

mcp for wsrx

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

15 Commits

Folders and files

Repository files navigation

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

Tool Description
wsrx_connect(remote, local_port?, wait?) Forward a local TCP port to a ws:///wss:// URL. For the same remote, an existing tunnel is reused; a free port is picked automatically when not specified; by default the call returns only once the local port is actually connectable.
wsrx_list() List tunnels: remote, local port, endpoint, PID, alive.
wsrx_disconnect(local_port? | remote?) Close a tunnel by its local port or remote URL.
wsrx_stop_all() Close every tunnel.
wsrx_doctor() Check the wsrx binary is on PATH and list current tunnels.

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)

Variable Default Description
WSRX_BINARY wsrx Path/resolved name of the wsrx executable.
WSRX_MCP_BIND_HOST 127.0.0.1 Address tunnels bind to. Use 0.0.0.0 only if other hosts must reach the tunnels.
WSRX_MCP_STARTUP_TIMEOUT 15 How long to wait for the local port to become connectable, in seconds.

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

About

mcp for wsrx

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages