zrok-mcp

An MCP server for zrok — the open-source secure sharing platform built on OpenZiti. Lets AI agents manage zrok tunnels, shares, and access programmatically.

Supports three transports: stdio (local), streamable-http and SSE (remote/Bifrost).

Tools

Each tool uses an action parameter to select the operation — no need to remember many tool names.

zrok_env — Environment management

Action	Description
status	Check environment status (enabled, API endpoint, identity)
enable	Enable the zrok environment with an account token
disable	Disable the current zrok environment

zrok_share — Share management

Action	Description
create	Create a public or private share
delete	Delete a share by token
list	List all shares with optional filters

zrok_access — Access management

Action	Description
create	Create access to a private share
delete	Remove access to a share
list	List all accesses with optional filters

Requirements

• Python 3.10+
• zrok2 Python SDK
• A zrok account and enabled environment

Install

cd zrok-mcp
pip install -e .

Run

Transport is selected via the ZROK_MCP_TRANSPORT environment variable (default: stdio).

Transport	Use case
stdio	Local clients (Claude Desktop, Cursor, Crush)
streamable-http	Remote / Bifrost gateway (recommended)
sse	Remote / Bifrost gateway (legacy SSE)

STDIO (default)

zrok-mcp

Streamable HTTP (remote)

ZROK_MCP_TRANSPORT=streamable-http ZROK_MCP_PORT=8000 zrok-mcp

Docker (remote)

docker build -t zrok-mcp .
docker run -p 8000:8000 -v ~/.zrok2:/root/.zrok2 zrok-mcp

With MCP Inspector

mcp dev src/zrok_mcp/server.py

Environment Variables

Variable	Default	Description
ZROK_MCP_TRANSPORT	stdio	Transport: stdio, streamable-http, or sse
ZROK_MCP_HOST	0.0.0.0	Bind host (HTTP/SSE transports)
ZROK_MCP_PORT	8000	Bind port (HTTP/SSE transports)

Configuration

Claude Desktop (stdio)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "zrok": {
      "command": "uv",
      "args": ["--directory", "/path/to/zrok-mcp", "run", "zrok-mcp"]
    }
  }
}

Cursor / Crush (stdio)

Add to your crush settings or MCP config:

{
  "zrok": {
    "command": "uv",
    "args": ["--directory", "/path/to/zrok-mcp", "run", "zrok-mcp"]
  }
}

Bifrost AI Gateway (streamable-http)

1. Deploy zrok-mcp as a remote HTTP server (Docker, Railway, etc.)
2. In the Bifrost Web UI, go to MCP Gateway → New MCP Server
3. Select HTTP as the connection type
4. Enter the URL: http://your-zrok-mcp-host:8000/mcp
5. Set tools_to_execute to ["*"] (or filter as needed)

Or via config file:

{
  "mcp": {
    "mcp_clients": [
      {
        "name": "zrok",
        "connection_type": "http",
        "connection_string": "http://your-zrok-mcp-host:8000/mcp",
        "tools_to_execute": ["*"]
      }
    ]
  }
}

For SSE transport, use connection_type: "sse" and connection_string: "http://your-zrok-mcp-host:8000/sse".

Example Usage

Once configured, your AI agent can do things like:

"Share my local server on port 3000 publicly via zrok"

The agent will call zrok_share(action="create", target="http://localhost:3000") and return the public URL.

"List all my zrok shares"

The agent will call zrok_share(action="list") and show token, mode, target, and endpoints.

"Create a private TCP tunnel for my database on port 5432"

The agent will call zrok_share(action="create", share_mode="private", backend_mode="tcpTunnel", target="localhost:5432").

License

MIT