@teamnetwork-nz/tailscale-mcp-server

An MCP server for the Tailscale API, giving MCP clients access to tailnet devices, ACLs, DNS settings, subnet routes, and auth keys.

Compatible with Claude Desktop, Claude Code, Cursor, Cline, and any MCP-capable client.

Requirements

• Node.js 18+
• A Tailscale API access token (Tailscale admin console → Settings → Keys), or an OAuth client secret with the required scopes

Installation

npx @teamnetwork-nz/tailscale-mcp-server

Or install globally:

npm install -g @teamnetwork-nz/tailscale-mcp-server
tailscale-mcp-server

Configuration

Set these environment variables before starting the server:

Required

| Variable | Description | |---|---| | TAILSCALE_API_KEY | Access token from the admin console's Keys page, or an OAuth client's access token |

Optional

| Variable | Default | Description | |---|---|---| | TAILSCALE_TAILNET | - | Tailnet to operate on. - means "the default tailnet for the API key/OAuth client". Otherwise use the tailnet's full name, e.g. example.com | | TAILSCALE_READWRITE | false | Set to true to enable write tools (device management, ACL/DNS updates, auth key management) | | TAILSCALE_BASE_URL | https://api.tailscale.com/api/v2 | Override the API base URL (rarely needed) | | TAILSCALE_TIMEOUT_MS | 8000 | Per-request connect/response timeout in milliseconds | | TAILSCALE_IPV4_ONLY | false | Set to true to force IPv4-only DNS resolution. Fixes slow/hanging requests on hosts with no working IPv6 route, where dual-stack (Happy Eyeballs) resolution has to time out on IPv6 before falling back | | TAILSCALE_TRANSPORT | stdio | Transport mode: stdio (default, local) or http (remote agent hosting) | | TAILSCALE_HTTP_PORT | 3000 | Port to listen on when TAILSCALE_TRANSPORT=http | | TAILSCALE_HTTP_HOST | 127.0.0.1 | Bind address when TAILSCALE_TRANSPORT=http | | TAILSCALE_HTTP_BEARER_TOKEN | unset | Token required in Authorization: Bearer ...; mandatory for non-loopback binding | | TAILSCALE_HTTP_ALLOWED_HOSTS | unset | Comma-separated allowed Host header values; mandatory for non-loopback binding | | TAILSCALE_HTTP_ALLOWED_ORIGINS | unset | Comma-separated browser origins permitted to call /mcp | | TAILSCALE_HTTP_MAX_BODY_BYTES | 1048576 | Maximum HTTP request body size |

Tools

Read (always available)

| Tool | Description | |---|---| | list_devices | List tailnet devices, optionally filtered by name or tag | | get_device | Full details for a single device | | get_device_routes | Advertised and enabled subnet routes for a device | | list_auth_keys | List auth keys / OAuth clients (no secret material) | | get_auth_key | Metadata for a single auth key | | get_dns_nameservers | Tailnet global DNS nameservers | | get_dns_preferences | MagicDNS enabled/disabled | | get_dns_searchpaths | Tailnet DNS search paths | | get_acl | Current ACL policy file (HuJSON) |

Write (requires TAILSCALE_READWRITE=true)

| Tool | Description | |---|---| | authorize_device | Authorize or deauthorize a device | | delete_device | Remove a device from the tailnet | | set_device_tags | Replace a device's ACL tags | | expire_device_key | Immediately expire a device's node key | | set_device_routes | Enable/disable a device's advertised subnet routes | | create_auth_key | Create a new auth key | | delete_auth_key | Revoke an auth key | | set_dns_nameservers | Replace the tailnet's DNS nameservers | | set_dns_preferences | Enable/disable MagicDNS | | set_dns_searchpaths | Replace the tailnet's DNS search paths | | update_acl | Replace the full ACL policy file |

Claude Desktop configuration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "tailscale": {
      "command": "npx",
      "args": ["-y", "@teamnetwork-nz/tailscale-mcp-server"],
      "env": {
        "TAILSCALE_API_KEY": "tskey-api-your-key-here"
      }
    }
  }
}

Claude Code configuration

claude mcp add tailscale \
  -e TAILSCALE_API_KEY=tskey-api-your-key-here \
  -- npx -y @teamnetwork-nz/tailscale-mcp-server

Running as a remote HTTP server

Set TAILSCALE_TRANSPORT=http to start an HTTP server instead of reading from stdin. The server exposes a single endpoint at /mcp using the MCP Streamable HTTP transport in stateless mode. A health check is available at GET /health.

TAILSCALE_API_KEY=tskey-api-your-key \
TAILSCALE_TRANSPORT=http \
TAILSCALE_HTTP_BEARER_TOKEN=replace-with-a-long-random-secret \
npx @teamnetwork-nz/tailscale-mcp-server

The listener defaults to loopback. To expose it directly or from a container, set TAILSCALE_HTTP_HOST=0.0.0.0, TAILSCALE_HTTP_BEARER_TOKEN, and TAILSCALE_HTTP_ALLOWED_HOSTS (including the port when one appears in the request's Host header). TLS should be terminated by a trusted reverse proxy.

Development

npm install
npm run build
npm start

Security notes

• The server runs in read-only mode by default. Write tools must be explicitly enabled via TAILSCALE_READWRITE=true.
• Remote HTTP access is restricted to loopback by default. Non-loopback listeners require bearer authentication and an explicit host allowlist.
• delete_device, expire_device_key, and update_acl are disruptive and effectively irreversible — review the tool descriptions and confirm with the model/client before granting write access in a production tailnet.
• create_auth_key returns the plaintext key exactly once in the tool response. It cannot be retrieved again — store it immediately.