Tailscale MCP Server

A Bun-based Model Context Protocol server for operating Tailscale from MCP clients.

It supports local stdio usage for desktop clients and an authenticated HTTP transport for private tailnet deployments. The server defaults to read-only access, localhost binding, and short-lived OAuth credentials where available.

Features

• Tailscale device, route, DNS, ACL, key, webhook, exit-node, and tag management.

• Read-only MCP resources for tailnet summaries, devices, and ACL state.

• MCP prompts for connectivity diagnosis and ACL review.

• Risk-gated tools: read, write, and admin.

• OAuth client credentials with API key compatibility.

• Private HTTP mode with bearer auth, host validation, request limits, and health checks.

• Docker support for local builds and private Tailscale Serve deployments.

Related MCP server: ConnectWise API Gateway MCP Server

Requirements

• Bun 1.3 or newer.

• Tailscale API access through one of:

  • OAuth client credentials: TAILSCALE_OAUTH_CLIENT_ID and TAILSCALE_OAUTH_CLIENT_SECRET.

  • Legacy API key: TAILSCALE_API_KEY.

• Local Tailscale CLI for CLI-backed tools such as status, ping, connect, and disconnect.

MCP Client Setup

Use stdio for local MCP clients.

{
  "mcpServers": {
    "tailscale": {
      "command": "bunx",
      "args": ["@hexsleeves/tailscale-mcp-server"],
      "env": {
        "TAILSCALE_OAUTH_CLIENT_ID": "your-client-id",
        "TAILSCALE_OAUTH_CLIENT_SECRET": "your-client-secret",
        "TAILSCALE_TAILNET": "-"
      }
    }
  }
}

For API key compatibility:

{
  "mcpServers": {
    "tailscale": {
      "command": "bunx",
      "args": ["@hexsleeves/tailscale-mcp-server"],
      "env": {
        "TAILSCALE_API_KEY": "tskey-...",
        "TAILSCALE_TAILNET": "-"
      }
    }
  }
}

HTTP Transport

HTTP mode is intended for private tailnet access. It requires MCP_HTTP_BEARER_TOKEN and binds to 127.0.0.1 by default.

export MCP_TRANSPORT=http
export MCP_HTTP_BEARER_TOKEN="$(openssl rand -base64 32)"
export TAILSCALE_OAUTH_CLIENT_ID="your-client-id"
export TAILSCALE_OAUTH_CLIENT_SECRET="your-client-secret"
export TAILSCALE_TAILNET="-"

bun run src/index.ts --http --host 127.0.0.1 --port 3000

Expose HTTP mode privately with Tailscale Serve:

tailscale serve --bg 443 localhost:3000

Do not use Funnel for normal MCP operation. Funnel makes the endpoint publicly reachable and should be reviewed separately.

Configuration

Risk levels:

• read: list devices, inspect status, read resources, and run diagnostics.

• write: update ACLs, DNS, routes, policy files, webhooks, tags, and other mutating tailnet settings.

• admin: destructive or host-affecting operations such as delete, deauthorize, connect, disconnect, auth key mutation, and file sharing changes.

Capabilities

Tools:

• Devices: list_devices, device_action, manage_routes.

• Network: get_network_status, connect_network, disconnect_network, ping_peer, get_version.

• Administration: get_tailnet_info, manage_acl, manage_dns, manage_keys, manage_policy_file, manage_file_sharing, manage_exit_nodes, manage_webhooks, manage_device_tags.

Resources:

• tailscale://tailnet/summary

• tailscale://devices

• tailscale://devices/{deviceId}

• tailscale://acl/current

Prompts:

• diagnose_tailnet_connectivity

• review_acl_change

Docker

Build locally:

docker build -t tailscale-mcp-server .

Run HTTP mode on localhost:

docker run --rm \
  -e MCP_HTTP_BEARER_TOKEN="$MCP_HTTP_BEARER_TOKEN" \
  -e TAILSCALE_OAUTH_CLIENT_ID="$TAILSCALE_OAUTH_CLIENT_ID" \
  -e TAILSCALE_OAUTH_CLIENT_SECRET="$TAILSCALE_OAUTH_CLIENT_SECRET" \
  -e TAILSCALE_TAILNET="-" \
  -p 127.0.0.1:3000:3000 \
  tailscale-mcp-server

Or use the published image:

docker run --rm \
  -e MCP_HTTP_BEARER_TOKEN="$MCP_HTTP_BEARER_TOKEN" \
  -e TAILSCALE_OAUTH_CLIENT_ID="$TAILSCALE_OAUTH_CLIENT_ID" \
  -e TAILSCALE_OAUTH_CLIENT_SECRET="$TAILSCALE_OAUTH_CLIENT_SECRET" \
  -e TAILSCALE_TAILNET="-" \
  -p 127.0.0.1:3000:3000 \
  hexsleeves/tailscale-mcp-server:latest

For a sidecar deployment that exposes the server with private Tailscale Serve, see deploy/README.md.

Development

bun install
bun run typecheck
bun test
bun run check
bun run build

Full verification:

bun run qa:full

Security audit:

bun audit