Tailscale MCP Server

@yawlabs/tailscale-mcp

One click adds this to your local Yaw MCP config so it's available in every Yaw Terminal session. Or install manually below.

Ask your agent questions about your tailnet and have it act on the answers. 97 admin-API tools + 6 optional local-CLI diagnostics + 1 always-on catalog tool + 4 resources spanning the Tailscale v2 API — devices, ACLs, DNS, keys and trust credentials, users, invites, webhooks, log streaming, posture, services, and organization tailnets. Backed by 1900+ unit tests and an opt-in live-tailnet integration suite.

Built and maintained by Yaw Labs.

What's the point if the API already exists?

You could curl the Tailscale API. The point isn't replacing curl — it's letting an agent compose multi-endpoint workflows in one turn without writing a script:

• "Which devices haven't checked in for 30 days and have key expiry disabled?" — lists devices, filters by lastSeen (online devices carry none), filters by keyExpiryDisabled, returns a table. Three endpoints, one question.
• "Someone broke DNS at 2am — who changed what in the last 24 hours?" — pulls the audit log, filters by DNS-related actors and endpoints, reads each change's before/after, summarizes in English.
• "Draft an ACL change that lets `tag:mobile` reach `tag:dashboard` but not `tag:db`, preserving my comments" — reads the current HuJSON, proposes a minimal diff, validates it against the API, returns the diff for you to apply.
• "Rotate every auth key older than 90 days and print the new ones" — iterates, creates new keys with matching tags, revokes the old ones.
• "Create an OAuth client for our CI pipeline scoped to `devices:core:read` and `dns:read`" — creates a trust credential via tailscale_create_key with keyType=client, returns the credentials once (save them immediately).

A curl can do each step. The agent composes them. That's where the lift is, and that's what the tool surface is designed for — every read endpoint is first-class so the agent can synthesize, and every write endpoint is tagged destructiveHint or idempotentHint so your MCP client can gate mutations the way you configured it.

If all you need is one endpoint in a CI job, use curl — we even have a CLI subcommand for the common ACL-from-git case. The MCP is for the interactive, exploratory, "I don't know what I need yet" work.

Why MCP vs. a skill or the tailscale CLI?

Reasonable question. Both have their place. Where this MCP is better:

• Broad admin API coverage. The tailscale CLI is scoped to the node it runs on. Admin concerns — ACLs, users, invites, webhooks, log streaming, posture integrations, auth keys, OAuth clients, and federated identities — live in the v2 HTTP API. You'd be shelling out to curl anyway.
• Typed tool surface, not string parsing. Every tool has a Zod-validated input schema and a structured response. No brittle tailscale status --json | jq pipelines that break when the schema evolves.
• Cross-client, and updates arrive as a version bump. An MCP server works in Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, and anything else that speaks MCP; a skill written to the Agent Skills standard travels between agents too, but it is prose you maintain. Version bumps ship through npx — nobody rewrites a skill's instructions when Tailscale adds an endpoint.
• Safe-by-default writes. Every tool declares readOnlyHint / destructiveHint / idempotentHint so clients can skip confirmation on reads and require it on mutations. A skill that shells out to the CLI can't express that.
• Real tests. 1900+ unit tests covering every tool's input validation, API shape, and error handling. Plus an opt-in live-tailnet integration suite (RUN_INTEGRATION_TESTS=1 + a tailnet API key) for shape-drift detection. Most skills are short markdown prompts without their own test layer — if the vendor changes output format, nothing catches it for you.

If you already have a skill that covers your 10% of Tailscale workflows, great — keep it. The MCP is for the other 90%.

What about Tailscale's own MCP endpoints and skill? As of 2026-09-19 they solve different problems, and nothing here duplicates them. Tailscale's official MCP tools are two alpha built-in connectors inside Aperture: *Tailnet*, whose Tailnet_provision_node returns a single-use auth key so an agent can join one new node after a person approves it, and *Tailscale SSH*, whose TailnetSSH_list_machines and TailnetSSH_run_command discover SSH-enabled machines and run one command on one of them. They require Aperture. tailscale/tailscale-skill is an alpha, knowledge-only skill — reference material that teaches an agent to curl the v2 API, with no server of its own. Neither exposes the admin API as typed tools, so the overlap with this server is close to nil. Nor can Aperture front this one today: this server speaks stdio, and Aperture proxies only URL-addressable Streamable-HTTP or SSE servers. Both of those products are alpha, so treat the date on this paragraph as its expiry.

Trust signals

Fair critique from Reddit: a new repo claiming "actively maintained" with no visible tests is worth exactly zero trust. Here's what's actually verifiable:

• 1900+ tests (node --test) covering every tool's input validation, API shape, and error handling. Run npm test to see them pass locally.
• Local release flow via release.sh: lint + test + bump + tag + push + npm publish + MCP Registry publish, all from the workstation. No CI workflow to babysit.
• Dependabot alerts surface on this repo and get fixed, not ignored.
• Every tool names a real endpoint from the OpenAPI spec. If it's in the tool list, it calls a path documented in the current v2 API -- no placeholder 404 tools. To be clear about the limits of that: no recorded live exchange ships with this repo (fixtures/live/ is empty on purpose), and no claim here rests on an observation against a live tailnet.

Issues and PRs are triaged. File one if something is off — github.com/YawLabs/tailscale-mcp/issues.

Quick start

1. Set your API key

Get an API key from Tailscale Admin Console > Settings > Keys and set it where your MCP client will see it. The .mcp.json env block in step 2 works identically on every platform and is the option to prefer; to export it from a shell profile instead (~/.bashrc, ~/.zshrc, ~/.config/fish/config.fish):

macOS / Linux / WSL (bash, zsh):

export TAILSCALE_API_KEY="tskey-api-..."

fish:

set -Ux TAILSCALE_API_KEY tskey-api-...

Windows (PowerShell 5.1 and 7) — [Environment]::SetEnvironmentVariable persists it for the user, where $env: alone lasts only for the session:

[Environment]::SetEnvironmentVariable('TAILSCALE_API_KEY', 'tskey-api-...', 'User')

2. Create `.mcp.json` in your project root

macOS / Linux / WSL:

{

"mcpServers": { "tailscale": { "command": "npx", "args": ["-y", "@yawlabs/tailscale-mcp@latest"] } } }

Windows:

{

"mcpServers": { "tailscale": { "command": "cmd", "args": ["/c", "npx", "-y", "@yawlabs/tailscale-mcp@latest"] } } }

Why the extra step on Windows? On Windows, npx is a .cmd file, and Node 20+ refuses to spawn .cmd files directly. Wrapping with cmd /c is the standard workaround.

3. Restart and approve

Restart Claude Code (or your MCP client) and approve the Tailscale MCP server when prompted.

That's it. Now ask your agent:

"List my Tailscale devices that haven't been seen in the last 7 days"

"Summarize every ACL change in the audit log from yesterday"

"Draft an ACL rule that lets tag:ci reach tag:registry on port 5000 only"

Too many tools? Subset them.

97 tools is a lot. If you've already got a dozen MCP servers and your client is feeling heavy, trim what this one exposes. Three knobs, combinable:

The env blocks below show only the variable under discussion. Your credentials come from the environment, as set in Quick start — keep them in your shell profile rather than in the client's JSON config, which is world-readable on most systems and easy to commit by accident.

Option 1: TAILSCALE_PROFILE (preset, easiest)

{

"env": { "TAILSCALE_PROFILE": "core" } }

• `minimal` (20 tools) — status, devices, audit. Observe the tailnet, read the audit log.
• `core` (52 tools) — adds acl, dns, keys, users. The day-to-day admin surface.
• `full` (97 tools, default) — everything. Same as omitting the env var.

Profile names are case-insensitive and ignore surrounding whitespace (Core selects core). The group names in TAILSCALE_TOOLS and TAILSCALE_WRITE_GROUPS are case-sensitive.

Option 2: TAILSCALE_TOOLS (explicit group list)

{

"env": { "TAILSCALE_TOOLS": "devices,acl,dns,audit" } }

Comma-separated group names. Overrides TAILSCALE_PROFILE when both are set — use this when the presets aren't quite right.

Valid group names: status, devices, acl, dns, keys, users, tailnet, org-tailnets, webhooks, posture, audit, invites, services, log-streaming. The local-cli group is also available, but only when TAILSCALE_LOCAL_CLI=1 is set — see Local CLI integration.

Option 3: TAILSCALE_READONLY (drop mutations)

{

"env": { "TAILSCALE_PROFILE": "core", "TAILSCALE_READONLY": "1" } }

Set to 1 or true to drop every tool without readOnlyHint: true. Stacks with TAILSCALE_PROFILE or TAILSCALE_TOOLS as an intersection — combine for maximum minimalism.

Confirming what loaded

The server logs the active filter to stderr on startup:

@yawlabs/tailscale-mcp v0.22.0 ready (20 tools, profile=minimal, readonly)

When both TAILSCALE_PROFILE and TAILSCALE_TOOLS are set, TAILSCALE_TOOLS wins. The banner marks the profile as overridden so the precedence is obvious at a glance — no need to guess which filter actually applied:

@yawlabs/tailscale-mcp v0.22.0 ready (22 tools, profile=core (overridden by TAILSCALE_TOOLS), groups=devices,acl)

The "(overridden)" marker only fires for substantive profiles (minimal / core); profile=full is a no-op preset, so it's shown without the marker when TAILSCALE_TOOLS is also set.

If you don't set any filter, startup prints a tip pointing you at the profiles.

And how the *agent* knows

Everything above is stderr -- your MCP client's log. The model never sees it, so a withheld tool and a tool that was never built look identical from the agent's side. That is how an agent ends up working around a restriction instead of reporting it.

tailscale_tool_groups closes that gap. It is always registered, whatever the filters say, and answers the question in-band:

> "Why c