Use TezTun from Claude Code & Claude Desktop

Updated April 2026 · 4 min read

The TezTun CLI ships with a built-in Model Context Protocol server. Once configured, your AI assistant — Claude Code, Claude Desktop, Cursor, Zed, Windsurf — can read and manage your TezTun infrastructure directly in the conversation. Ask it "what's my webhook URL" or "show me my active tunnels" and it answers from your live account.

What you can do from the chat

More tools (create/revoke tokens, reserve/release subdomains, list custom domains) are shipping in upcoming releases.

Requirements

1. The TezTun CLI installed on your machine, or the asadullokhn/teztun Docker image.
2. A service token from app.teztun.uz/tokens. On Max plan tokens never expire — recommended for long-running editors. On Pro they're valid 3 days; on Free only 6 hours, which isn't practical.

Configuration

Three ways to run the server, pick whichever matches your setup. The npx one works everywhere Node.js is installed and is the recommended default.

Option A — npx (recommended)

No install. Works on any machine with Node 18+.

Claude Code

claude mcp add --scope user teztun \
  -e TEZTUN_TOKEN=tzt_your-token-here \
  -- npx -y @asadullokhn/teztun-mcp

Claude Desktop

{
  "mcpServers": {
    "teztun": {
      "command": "npx",
      "args": ["-y", "@asadullokhn/teztun-mcp"],
      "env": { "TEZTUN_TOKEN": "tzt_your-token-here" }
    }
  }
}

The @asadullokhn/teztun-mcp package is a thin launcher. It uses the teztun CLI if installed, otherwise falls back to the asadullokhn/teztun Docker image.

Option B — installed CLI

Faster to start (no docker / no npx). Install the TezTun CLI first.

Claude Code

claude mcp add --scope user teztun \
  -e TEZTUN_TOKEN=tzt_your-token-here \
  -- teztun mcp

Restart your Claude Code session. Type /mcp to confirm TezTun is listed and connected.

Claude Desktop

Edit the config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "teztun": {
      "command": "teztun",
      "args": ["mcp"],
      "env": {
        "TEZTUN_TOKEN": "tzt_your-token-here"
      }
    }
  }
}

Quit and relaunch Claude Desktop. The tools show up in the tool picker.

Option C — explicit Docker

No Node, no CLI — just Docker. Useful for locked-down environments.

{
  "mcpServers": {
    "teztun": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "TEZTUN_TOKEN",
        "asadullokhn/teztun:latest", "mcp"
      ],
      "env": { "TEZTUN_TOKEN": "tzt_your-token-here" }
    }
  }
}

Cursor, Zed, Windsurf

Each editor has its own MCP config file (~/.cursor/mcp.json, etc.) but the block shape is identical to Claude Desktop above. Paste the same "teztun" block.

What a session looks like

Once configured, a typical interaction:

You:  What's my current staging tunnel URL?
Claude:  [calls list_tunnels]
        You have 1 active tunnel:
          https://staging-api.ttn.uz  → app:3000
          1 active connection, started 18 minutes ago

You:  Which subdomains do I have reserved?
Claude:  [calls list_subdomains]
        You have 3 reserved subdomains on ttn.uz:
          staging-api  (in use by the tunnel above)
          hooks        (idle)
          demo         (idle)

Security

• The token is passed to the MCP server via the env section — it never leaves your machine. The AI client doesn't see it, only the tool responses.
• Revoke the token from the dashboard if you lose the machine or share it. Any AI client using that token loses access immediately.
• The current tools are read-only. You can't accidentally destroy resources by asking the wrong question.

Troubleshooting

Tools don't show up in Claude Desktop. Check the client log: ~/Library/Logs/Claude/mcp*.log (macOS). Look for the teztun entry. Most common cause: teztun isn't in the PATH the GUI app inherits. Use an absolute path (/usr/local/bin/teztun) in the command field.

"TEZTUN_TOKEN environment variable is not set" in every tool result. The token didn't propagate — make sure it's in the env block of the config, not your shell environment. GUI apps don't inherit shell env.

All tool calls return 401. Token is revoked or expired. Mint a new one at app.teztun.uz/tokens and update your config.