Tailscale MCP

Requirements

• Node.js 20+
• A Tailscale API key or OAuth client credentials

GitOps: deploy ACLs from CI

For the simple "deploy ACL from git on merge" workflow, you don't need an MCP server or an agent — use the built-in CLI:

npx -y @yawlabs/tailscale-mcp@latest deploy-acl tailscale/acl.json

Handles ETag fetching, validation, and deployment in one command. Works in any CI system. Set TAILSCALE_API_KEY and TAILSCALE_TAILNET as env vars.

Optional: Lock the Admin Console to prevent manual edits that drift from git. Ask your agent:

"Set aclsExternallyManagedOn to true and aclsExternalLink to our repo URL"

This shows a read-only banner in the Tailscale Admin Console pointing to your repo. Use the MCP for reads and investigations, and let CI handle the deploy.

Quick start

1. Set your API key

Get an API key from Tailscale Admin Console > Settings > Keys and add it to your shell profile (~/.bashrc, ~/.zshrc, or Windows system environment variables):

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

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"

Option 1: `TAILSCALE_PROFILE` (preset, easiest)

{
  "env": {
    "TAILSCALE_API_KEY": "tskey-api-...",
    "TAILSCALE_PROFILE": "core"
  }
}

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

Option 2: `TAILSCALE_TOOLS` (explicit group list)

{
  "env": {
    "TAILSCALE_API_KEY": "tskey-api-...",
    "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, 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_API_KEY": "tskey-api-...",
    "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.

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, 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:read and dns" — 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.

Local CLI integration (opt-in)

Most tools talk to the Tailscale v2 admin API — they describe the tailnet. Sometimes you want to ask about this machine's view: is it actually connected? What DERP region is it on? How far is my-laptop from here? Those answers come from the local tailscale binary, not the admin API.

Set TAILSCALE_LOCAL_CLI=1 (in your shell or .mcp.json env block) to add four read-only diagnostic tools:

Requirements: the tailscale binary must be in PATH. If it's installed somewhere unusual, set TAILSCALE_BINARY to its absolute path. The MCP server doesn't need root to run these — they're all diagnostic, not state-mutating. Operations that would need elevation (tailscale up, set --advertise-routes, lock sign) are deliberately not exposed.

When opt-in is on, the startup banner reflects it: @yawlabs/tailscale-mcp v0.10.9 ready (93 tools, local-cli=on).

Why MCP vs. a skill or the `tailscale` CLI?

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

• Full 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, no user rewriting. A Claude Code skill only loads in Claude Code. An MCP server works in Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, and anything else that speaks MCP. Version bumps ship through npx — users don't re-author their skill 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. 700+ 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%.