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```bash
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)```bash
zrok-mcp
Streamable HTTP (remote)```bash
ZROK_MCP_TRANSPORT=streamable-http ZROK_MCP_PORT=8000 zrok-mcp
### Docker (remote)```bash
docker build -t zrok-mcp .
docker run -p 8000:8000 -v ~/.zrok2:/root/.zrok2 zrok-mcp
With MCP Inspector```bash
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`:```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:```json
{
"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:```json
{
"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