rtailscale

# 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](#naming)
- [Capabilities And Boundaries](#capabilities-and-boundaries)
- [Install](#install)
- [Quickstart](#quickstart)
- [Client Configuration](#client-configuration)
- [Runtime Surfaces](#runtime-surfaces)
- [MCP Tool Reference](#mcp-tool-reference)
- [CLI Reference](#cli-reference)
- [Configuration](#configuration)
- [Authentication](#authentication)
- [Safety And Trust Model](#safety-and-trust-model)
- [Architecture](#architecture)
- [Distribution Contract](#distribution-contract)
- [Development](#development)
- [Verification](#verification)
- [Deployment](#deployment)
- [Troubleshooting](#troubleshooting)
- [Related Servers](#related-servers)
- [Documentation](#documentation)
- [License](#license)

## Naming

| Surface | This repo |
|---|---|
| Repository | `tailscale-rmcp` |
| Rust crate | `tailscale-rmcp` |
| Binary / CLI | `rtailscale` |
| npm package | `@dinglebear/rtailscale` |
| npm binary aliases | `tailscale-rmcp`, `rtailscale` |
| MCP tool | `tailscale` |
| Config home | `~/.tailscale-mcp` on hosts, `/data` in containers |
| Env prefixes | `TAILSCALE_*`, `TAILSCALE_MCP_*`, `TAILSCALE_RMCP_*` for npm launcher controls |

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.

| This repo owns | Tailscale owns | Explicitly out of scope |
|---|---|---|
| MCP/CLI projection, request validation, HTTP MCP auth policy, response shaping, setup checks, and destructive gates. | Tailnet state, device identities, ACL semantics, DNS behavior, API key issuance, user membership, and upstream authorization. | Replacing the admin console, storing caller credentials, multi-tailnet tenancy, arbitrary WireGuard control, policy editing beyond exposed actions, and local Tailscale daemon management. |

## Install

| Path | Command | Best for | Notes |
|---|---|---|---|
| npm / npx | `npx -y @dinglebear/rtailscale --help` | Local MCP clients and quick trials. | Downloads the matching `rtailscale` binary from GitHub Releases. |
| Release installer | `curl -fsSL https://raw.githubusercontent.com/dinglebear-ai/rtailscale/main/scripts/install.sh \| bash` | Host installs without Node. | Installs `rtailscale` for the current Linux host. |
| Docker / Compose | `docker compose up -d` | Shared HTTP MCP deployments. | Reads `.env` and exposes container port `40040`. |
| Build from source | `cargo build --release` | Development and audits. | Produces `target/release/rtailscale`. |
| Plugin | `claude plugin install plugins/tailscale` | Claude Code local plugin setup from this checkout. | Ships the skill, `.mcp.json`, and a bundled binary. No hooks — run `rtailscale setup check` yourself if you want the environment verified. |

### npm / npx

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

```bash
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:

| Variable | Purpose |
|---|---|
| `TAILSCALE_RMCP_SKIP_DOWNLOAD=1` | Skip postinstall binary download. |
| `TAILSCALE_RMCP_VERSION` or `TAILSCALE_RMCP_BINARY_VERSION` | Select the GitHub Release tag. |
| `TAILSCALE_RMCP_REPO` | Select the GitHub repo used for release downloads. |
| `TAILSCALE_RMCP_RELEASE_BASE_URL` | Select a custom release base URL. |

### Build From Source

```bash
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

```bash
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

```bash
npx -y @dinglebear/rtailscale devices --json
```

### 4. Start Loopback HTTP MCP

```bash
TAILSCALE_MCP_HOST=127.0.0.1 npx -y @dinglebear/rtailscale serve
```

In another shell:

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

### 5. Make A First MCP Call

```bash
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

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

### Claude Code HTTP

```json
{
  "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.

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

### Generic MCP JSON

```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

| Surface | Status | Entry point | Purpose |
|---|---:|---|---|
| MCP stdio | Supported | `rtailscale mcp`, `npx -y @dinglebear/rtailscale mcp` | Local child-process MCP clients. |
| MCP HTTP | Supported | `rtailscale serve`, `POST /mcp` | Streamable HTTP MCP for local or shared server deployments. |
| CLI | Supported | `rtailscale <command>` | Scriptable parity and debugging. |
| REST API | Not shipped | N/A | Tailscale already owns the REST API. |
| Web UI | Not shipped | N/A | Tailscale already owns the admin console. |

## MCP Tool Reference

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

### Read Actions

| Action | Description | Required params | Optional params |
|---|---|---|---|
| `devices` | List all devices in the tailnet. | none | none |
| `device` | Return one device. | `id` | none |
| `device_routes` | Return subnet routes for one device. | `id` | none |
| `keys` | List API keys in the tailnet. | none | none |
| `acl` | Return ACL policy JSON. | none | none |
| `dns` | Return DNS nameservers, search paths, and MagicDNS preferences. | none | none |
| `users` | List tailnet users. | none | none |
| `help` | Return built-in action documentation. | none | none |

### Write Actions

| Action | Description | Required params | Optional params |
|---|---|---|---|
| `authorize_device` | Approve a device for the tailnet. | `id` | none |

### Destructive Actions

| Action | Description | Required params | Optional params |
|---|---|---|---|
| `delete_device` | Permanently remove a device. | `id`, `confirm=true` | none |

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:

```bash
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.

## Config