Tailscale MCP Server

What Tailscale MCP Server does

Tailscale MCP Server connects an MCP client to the Tailscale v2 administration API. Its tool surface covers tailnet operations such as device inventory, device authorization, key settings, subnet routes, ACL policies, DNS configuration, and device posture attributes.

Read operations can return device status, IP addresses, operating systems, connection details, ACL text, ETags, DNS settings, and posture data. Write operations can authorize, deauthorize, rename, expire, or delete devices; change tags and routes; update posture attributes; modify ACL policy text; and replace DNS settings.

The server is suited to interactive administration through an AI assistant. An agent can inspect the current state, make a targeted change, and use validation or preview tools before applying policy changes.

How it works

The server runs as a local stdio process started with npx. MCP clients send typed tool calls to that process, which authenticates to Tailscale with TAILSCALE_API_KEY and makes requests to the administration API.

tailscale_status verifies the connection and reports the tailnet name and device count. tailscale_tool_groups is always available and explains which tool groups are loaded, including environment changes that can restore withheld groups or write access.

ACL updates require a read-before-write workflow. Retrieve the current policy with tailscale_get_acl, preserve the returned HuJSON text, and pass its ETag to tailscale_update_acl. tailscale_validate_acl, tailscale_preview_acl, and tailscale_diff_acl_access provide checks before applying a change. The access-diff operation can be truncated and reports skipped or failed comparisons, so its result should be read together with those status fields.

Several mutation tools replace complete collections rather than merging them. Device tags, enabled subnet routes, nameservers, search paths, and split DNS configuration should therefore be sent as the full desired state.

Setup and configuration

Create a Tailscale API key in the Tailscale Admin Console and expose it to the MCP client as TAILSCALE_API_KEY. A project-level .mcp.json can launch the package with:

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

On Windows, launch npx through cmd /c because npx is a .cmd executable. Restart the MCP client and approve the server when prompted. The server is intended for clients that support stdio MCP connections.

Tools and capabilities

• Check API authentication and inspect tool-group availability.
• List devices and retrieve detailed information by device ID.
• Authorize, deauthorize, delete, rename, or expire devices.
• Change device tags, IPv4 addresses, key settings, routes, and posture attributes.
• Apply authorization or posture updates across multiple devices.
• Read, validate, preview, compare, and update ACL policies.
• Read and replace nameservers, search paths, and split DNS mappings.

ACL policy updates require the ETag returned by the corresponding read operation, or ts-default for an initial write to an unedited tailnet. Device deletion and posture-attribute deletion are irreversible actions.

Limitations and notes

The server speaks stdio rather than a URL-addressable Streamable HTTP or SSE transport. API access depends on the permissions and validity of the configured Tailscale API key. Device and DNS setters that replace collections can remove entries omitted from the request. Batch authorization runs requests in parallel and can return partial failures; inspect the failed-device data and retry only the unsuccessful items when appropriate.

A connected device may omit lastSeen; in that case, connectedToControl: true indicates that it is online. An omitted value can also represent a device that has never connected, so the surrounding device fields must be considered.