tailscale-mcp

# tailscale-mcp

An MCP server for [Tailscale](https://tailscale.com). The node it runs on is
driven through the `tailscale` command-line interface; the tailnet behind it is
driven through the control-plane REST API.

[186 tools](docs/tools.md), one per verb, with real parameters and honest
annotations. Tailscale's own JSON comes back unmodified, so anything you
learned from Tailscale's documentation still applies. When something fails you
get a fixed error code and a hint, not a wall of standard error.

Both surfaces are optional and neither is fatal. No `tailscale` binary means the
tools that drive this node are not offered; no control-plane credential means the
tools that drive the tailnet are not. `tailscale-mcp diagnose` says which of the
two this machine has.

On macOS that binary is the `tailscale` shim the Tailscale application installs
into `/usr/local/bin`. The executable inside the application bundle is not a
substitute and is not accepted as one: run outside a login shell it starts the
GUI rather than answering, so the local tools would be offered and then fail on
every call.

## Install

| Channel | How |
|---|---|
| npm | `npx -y @tailscale-mcp/tailscale-mcp` — downloads the release binary for your machine and refuses to run it unless the release's own `SHA256SUMS` vouches for it |
| Container | `docker run -i --rm -e TAILSCALE_API_KEY ghcr.io/tailscale-mcp/tailscale-mcp` |
| Homebrew | `brew trust tailscale-mcp/tap && brew install tailscale-mcp/tap/tailscale-mcp` — Homebrew 6 will not load a third-party tap until it is trusted, and reports that as an `Invalid formula` error once per platform it knows |
| Bundle | Download the `.mcpb` for your platform from the [releases](https://github.com/tailscale-mcp/tailscale-mcp/releases) and open it — for MCP clients that install bundles, such as Claude Desktop |
| From source | `cargo install tailscale-mcp` |

Release archives are on the
[releases page](https://github.com/tailscale-mcp/tailscale-mcp/releases) with a
`SHA256SUMS` beside them: macOS and Linux on `x86_64` and `arm64`, and Windows
on `x86_64`.

## Point a client at it

```sh
tailscale-mcp setup claude-code
```

prints the snippet for your client — `claude-code`, `claude-desktop`, `vscode`,
`cursor` or `zed` — and says where it goes. It writes nothing: the snippet is
yours to paste, and it leaves the credential out, for the reason in the next
section.

Installed through npm there is nothing to install first, and the client can
carry the settings:

```jsonc
{
  "mcpServers": {
    "tailscale": {
      "command": "npx",
      "args": ["-y", "@tailscale-mcp/tailscale-mcp"],
      "env": {
        "TAILSCALE_MCP_ALLOW_WRITE": "true"
      }
    }
  }
}
```

That much is enough to start it. Without a credential it offers the tools that
drive this node and hides the ones that act on the tailnet, and
`tailscale-mcp diagnose` says which of the two you have.

## Authenticate

`setup` prints no credential of its own, because the file it prints into is one
people paste into issues and chats without rereading. Adding one is a separate,
deliberate step. Two shapes go in the `env` block above — an API access token:

```jsonc
"env": {
  "TAILSCALE_API_KEY": "tskey-api-…",
  "TAILSCALE_MCP_ALLOW_WRITE": "true"
}
```

or an OAuth client:

```jsonc
"env": {
  "TAILSCALE_OAUTH_CLIENT_ID": "k123456CNTRL",
  "TAILSCALE_OAUTH_CLIENT_SECRET": "tskey-client-…",
  "TAILSCALE_MCP_ALLOW_WRITE": "true"
}
```

The [credentials table](docs/configuration.md#credentials) has the other
shapes, including the JWT file for federated identity. Every tool is offered
with either of these: the choice is not about what you can do with the server,
which is why it is worth making on other grounds.

**Prefer the OAuth client for anything you keep.** The reason is what a client
configuration *is*: a file somebody writes once and then forgets, holding a
secret for as long as the tool is installed.

An API access token suits that badly on three counts. It belongs to a person
and carries everything that person can do, so what leaks with the file is their
whole account rather than the tools you turned on. It expires — which in a file
nobody has looked at since they wrote it does not present as an expired
credential, but as a server that has stopped working for no reason. And it is
itself the bearer token, so the thing at rest is the thing that opens the door.

An OAuth client inverts each of those. It belongs to the tailnet, so it outlives
whoever set it up and is revoked without touching that person's access. Its
scopes narrow it to what the toolsets you enabled actually call. It does not
expire on its own, and what sits in the file is not a key but the means of
minting one — the token it hands this server lasts an hour, so a copy taken from
a backup or a screen share is worth very little by the time it is used.

The API access token is what the control plane offers you first, and is the
quicker thing to try this out with. It is worth replacing once the file is one
you are going to keep.

## Tiers and presets

Two independent dials decide what a session offers.

**The tier** is how dangerous a tool is allowed to be. Read tools change nothing
and are always offered. Write tools change configuration that can be changed
back. Destructive tools remove something or expose something in a way that is
not simply undone — deleting a device, revoking a key, publishing a service to
the internet. Read is always on; write and destructive are off until they are
turned on, and a tool above the permitted tier is *not listed*, not refused
when called.

**The preset** is how much surface area is offered at all. `minimal` is what an
agent needs to answer questions and fix the common things; `core` adds the rest
of everyday administration; `full` adds the tailnet-wide and irreversible
corners. Two toolsets are in no preset and must be asked for by name:
`local-debug`, which is Tailscale's own diagnostic surface, and
`local-passthrough`, which is one tool that runs an arbitrary `tailscale`
subcommand.

| Preset | Read | With `--allow-write` | With `--allow-destructive` | Toolsets |
|---|---|---|---|---|
| `minimal` | 37 | 51 | 55 | 4 |
| `core` (default) | 57 | 106 | 126 | 13 |
| `full` | 68 | 126 | 155 | 18 |

Adding `--toolsets +local-debug,+local-passthrough` to `full` reaches all 186.

Some destructive tools ask for one more thing: a `confirm: true` argument. Those
are the ones that affect the whole tailnet, or that can cut this server off from
the node or tailnet it is driving — logging the node out, deleting its own
device, deploying a policy that locks the caller out. The server does not decide
they are wrong; it makes the caller say it meant them.

- **[docs/tools.md](docs/tools.md)** — every tool, its tier and what it does.
  Generated from the code.
- **[docs/configuration.md](docs/configuration.md)** — every environment
  variable and flag, with defaults.
- **[docs/errors.md](docs/errors.md)** — every error code and what to do about
  it.

## Resources, prompts and completions

Nine resources — eight fixed and one template addressed by device identifier —
give a client the local node's status, preferences, netcheck report and tailnet
lock state, and the tailnet's policy file, devices, DNS configuration and
settings. They are read-only, they appear only when their surface is on, and
there are no subscriptions.

Three prompts steer a sequence of tool calls: `diagnose_connectivity`,
`review_policy_change` and `audit_tailnet_access`. They follow the same rule as
the resources: each appears only when the surface it needs is on, and
`diagnose_connectivity`, which reads from both, stops at the steps the session
can actually take.

Of the four argument slots those two surfaces expose, three are completed, so
a client can offer the values rather than leave them to be guessed: the device
template's identifier, `diagnose_connectivity`'s peer, and
`audit_tailnet_access`'s subject — which offers users, tags and devices, in
that order, so that a tailnet of thousands of devices still shows its handful
of users within the hundred values the protocol sends. The fourth, `review_policy_change`'s goal, is
a sentence about intent, and completing it would be inventing one. Every value offered is one the server will
accept back — a device is offered by its MagicDNS name, never by a hostname two
machines might share — and a source that cannot answer completes to nothing
rather than to an error. The method is rate limited, as the specification asks,
because each keystroke is a request.

Note that the protocol completes a prompt argument and a resource template
variable, and nothing else: **tool arguments cannot be completed**, so this
helps the four slots above and none of the 186 tools. Client support is
uneven — Claude Code completes resource templates, VS Code completes both, and
several clients do neither — so this is an improvement where it is read and
inert everywhere else.

## Transports

Stdio by default. `--http` serves Streamable HTTP instead, on
`127.0.0.1:8449`, behind a bearer token in `TAILSCALE_MCP_HTTP_TOKEN`, with
host and origin allow-lists, a body limit, a per-address rate limit and an open
health endpoint. Binding anywhere but loopback needs either that token or
`--http-no-auth` said out loud.

## Security

**What the tiers do.** A tool above the permitted tier is not in the tool list,
so a caller cannot invoke it by guessing its name, and a model cannot be talked
into one that was never offered. The default is read-only. `confirm` on top of
the destructive tier is a second signal for the operations that are worth one.
Secrets never reach an argument list, a log line or an error message; a minted
key or invite URL is returned once, verbatim, and nothing here keeps a copy.
Every tool result and every error goes through the same redaction on the way
out.

**What the tiers do not do.** They are not an authorization system, and they are
not a sandbox.

- A t