tailscale-rmcp

Tailscale device, route, DNS, key, user, and ACL management over MCP and CLI.

It exposes one MCP tool, tailscale, plus the rtailscale CLI. Agents can list devices, inspect routes, read API keys, ACL policy, DNS settings, and users, authorize devices, and delete devices when the destructive gate is explicitly enabled.

30-second path: set TAILSCALE_API_KEY, then run npx -y @dinglebear/rtailscale devices --json -> start loopback HTTP with TAILSCALE_MCP_HOST=127.0.0.1 npx -y @dinglebear/rtailscale serve -> call tools/call with {"action":"devices"}.

Status: operational RMCP upstream-client server. Write-capable for device authorization; destructive device deletion requires both server opt-in and caller confirmation. HTTP MCP supports loopback dev mode, static bearer tokens, and Google OAuth through lab-auth.

Not for: replacing the Tailscale admin console, bypassing Tailscale account permissions, operating multiple unrelated tailnets from one trust boundary, storing API keys for callers, arbitrary WireGuard control, or passing Tailscale API keys through MCP tool arguments.

Contents

• Naming
• Capabilities And Boundaries
• Install
• Quickstart
• Client Configuration
• Runtime Surfaces
• MCP Tool Reference
• CLI Reference
• Configuration
• Authentication
• Safety And Trust Model
• Architecture
• Distribution Contract
• Development
• Verification
• Deployment
• Troubleshooting
• Related Servers
• Documentation
• License

Naming

The repo, crate, and npm package use the RMCP family name. The shipped binary is rtailscale to avoid shadowing the official tailscale CLI.

Capabilities And Boundaries

• List devices and inspect a single device by node ID or legacy numeric device ID.
• Read subnet routes, API keys, ACL policy, DNS/MagicDNS settings, and tailnet users.
• Authorize a device for the tailnet.
• Delete a device only when TAILSCALE_ALLOW_DESTRUCTIVE=true and the caller also passes explicit confirmation.
• Provide setup and doctor commands for local plugin/runtime checks.

Install

npm / npx

Run the stdio MCP server or CLI without a manual binary install:

npx -y @dinglebear/rtailscale --help
npx -y @dinglebear/rtailscale mcp
npx -y @dinglebear/rtailscale devices --json

The npm package downloads rtailscale during postinstall. Override download behavior only when testing packaging:

Build From Source

git clone https://github.com/dinglebear-ai/rtailscale
cd rtailscale
cargo build --release
./target/release/rtailscale --help

Minimum supported Rust version: 1.86.

Quickstart

1. Get A Tailscale API Key

Create an API key at https://login.tailscale.com/admin/settings/keys. Use the minimum capability needed for the actions you plan to expose.

2. Configure The Tailnet

export TAILSCALE_API_KEY="tskey-api-..."
export TAILSCALE_TAILNET="-"          # personal, or "example.com" for orgs

Every Tailscale account belongs to a tailnet. TAILSCALE_TAILNET=- targets the default personal tailnet; organization tailnets usually use the org domain.

3. Run A Safe CLI Call

npx -y @dinglebear/rtailscale devices --json

4. Start Loopback HTTP MCP

TAILSCALE_MCP_HOST=127.0.0.1 npx -y @dinglebear/rtailscale serve

In another shell:

curl -sf http://127.0.0.1:40040/health

5. Make A First MCP Call

curl -s -X POST http://127.0.0.1:40040/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"tailscale","arguments":{"action":"devices"}}}'

Client Configuration

Claude Code Stdio

{
  "mcpServers": {
    "tailscale": {
      "command": "npx",
      "args": ["-y", "tailscale-rmcp", "mcp"],
      "env": {
        "TAILSCALE_API_KEY": "tskey-api-...",
        "TAILSCALE_TAILNET": "-"
      }
    }
  }
}

Claude Code HTTP

{
  "mcpServers": {
    "tailscale": {
      "type": "http",
      "url": "http://127.0.0.1:40040/mcp",
      "headers": {
        "Authorization": "Bearer ${TAILSCALE_MCP_TOKEN}"
      }
    }
  }
}

Codex / Labby Gateway

Register Tailscale through Labby as an HTTP upstream when sharing one long-running server, or run it directly as stdio for local-only use.

[mcp_servers.tailscale]
command = "npx"
args = ["-y", "tailscale-rmcp", "mcp"]

Generic MCP JSON

{
  "command": "rtailscale",
  "args": ["mcp"],
  "env": {
    "TAILSCALE_API_KEY": "tskey-api-...",
    "TAILSCALE_TAILNET": "-"
  }
}

Do not put TAILSCALE_API_KEY, OAuth secrets, passwords, SSH keys, or upstream bearer tokens in MCP tool arguments. Use env, config files, or the MCP client's secret storage. MCP callers never provide credentials, tokens, keys, or secrets as action arguments.

Runtime Surfaces

MCP Tool Reference

One MCP tool is exposed: tailscale. Pass the required action argument to select the operation.

Read Actions

Write Actions

Destructive Actions

Device IDs may be stable node IDs such as n1234abc or legacy numeric device IDs. Use action=devices first to discover IDs.

CLI Reference

The binary calls the same service layer as the MCP tool:

rtailscale devices [--json]
rtailscale device <id> [--json]
rtailscale routes <device-id> [--json]
rtailscale keys [--json]
rtailscale acl [--json]
rtailscale dns [--json]
rtailscale users [--json]
rtailscale authorize <device-id> [--json]
rtailscale delete-device <device-id> --confirm [--json]
rtailscale doctor [--json]
rtailscale setup check [--json]
rtailscale setup repair [--json]
rtailscale setup plugin-hook [--no-repair] [--json]
rtailscale serve            # HTTP MCP (also the no-argument default)
rtailscale mcp              # stdio MCP

All commands currently print JSON. --json is accepted for parity with the rest of the RMCP family.