Tailscale MCP Server

A Model Context Protocol (MCP) server for operating Tailscale from any MCP client. Supports local stdio for desktop clients and an authenticated HTTP transport for private tailnet deployments. Defaults to read-only access, localhost binding, and short-lived OAuth credentials where available.

Table of Contents

• Features
• Requirements
• Quick Start
  • Claude Desktop
  • Claude Code (CLI)
  • Cursor
• Tool Reference
• Resources and Prompts
• Configuration
• HTTP Transport
• Docker
• Example Prompts
• Development
• Contributing

Features

• Device management — list, authorize, deauthorize, delete, expire keys, manage routes.
• Network operations — connect/disconnect host, ping peers, get CLI status and version.
• Administration — tailnet info, file sharing, exit nodes, webhooks, device tags, server version.
• ACL and policy — read/validate/update ACL, DNS settings, auth keys, policy file, network lock.
• Read-only resources — tailnet summary, device list, per-device detail, current ACL.
• Prompts — guided connectivity diagnosis and ACL change review.
• Risk-gated tools — read, write, and admin levels via TAILSCALE_ALLOWED_TOOL_RISK.
• OAuth + API key — OAuth client credentials (preferred) or legacy API key.
• Private HTTP mode — bearer auth, Host validation, request size limits, health check endpoint.
• Docker support — pre-built images on Docker Hub and GHCR; sidecar deployment with Tailscale Serve.

Requirements

One of:

• Node.js 20+ — run via npx or install globally (no extra runtime needed).
• Bun 1.3+ — used for development; also works as a production runtime.
• Docker — use the pre-built image (no local runtime required).

Plus one auth method:

• OAuth client credentials: TAILSCALE_OAUTH_CLIENT_ID + TAILSCALE_OAUTH_CLIENT_SECRET (preferred).
• Legacy API key: TAILSCALE_API_KEY.

The local Tailscale CLI is optional. It is only required for CLI-backed tools: get_network_status, connect_network, disconnect_network, ping_peer, get_version, and manage_exit_nodes (set/clear operations).

Quick Start

Claude Desktop

Edit ~/.claude/claude_desktop_config.json (create if absent).

OAuth credentials (recommended)

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

API key

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

Enable write/admin tools

Add TAILSCALE_ALLOWED_TOOL_RISK to the env block:

"TAILSCALE_ALLOWED_TOOL_RISK": "write"

Set to "admin" to unlock destructive operations (delete, deauthorize, connect/disconnect, key mutation).

Docker Hub