mcp-tailscale

MCP server wrapping Tailscale CLI — manage devices, serve configs, and diagnose connectivity from any MCP-capable AI agent (Hermes, Claude Code, etc.).

Tools

Tool	Description
`list_devices`	All peers with status, OS, IPs, connection type, traffic
`device_info`	Detailed info about self or a specific peer
`netcheck`	NAT/connectivity diagnostics + DERP relay latency
`serve_list`	Current Tailscale Serve / Funnel configurations
`serve_add`	Expose a local port over Tailscale (tcp/http/https)
`serve_remove`	Remove a Tailscale Serve configuration
`ping`	Ping a peer via Tailscale and show the route
`whois`	Machine and user behind a Tailscale IP

Quick Start

pip install mcp-tailscale
# or
pip install git+https://github.com/gumbyender/mcp-tailscale.git

Then configure in your MCP client:

Hermes Agent

Add to ~/.hermes/config.yaml:

mcp_servers:
  tailscale:
    command: "mcp-tailscale"

Restart Hermes. Tools appear as mcp_tailscale_*.

Claude Desktop

{
  "mcpServers": {
    "tailscale": {
      "command": "mcp-tailscale"
    }
  }
}

VS Code / Cline / Continue

{
  "mcpServers": {
    "tailscale": {
      "command": "mcp-tailscale"
    }
  }
}

Requirements

Tailscale — installed and logged in (tailscale status must work)
Python 3.11+
mcp package (installed automatically as a dependency)

Development

git clone https://github.com/gumbyender/mcp-tailscale.git
cd mcp-tailscale
pip install -e .

Test the server starts correctly:

mcp-tailscale
# or
python -m mcp_tailscale

The server will start listening on stdio — connect your MCP client to it.

Companion Skill

The SKILL.md in this repo is a Hermes-compatible skill for "secure homelab networking with Tailscale + self-hosted agents." To install it in Hermes:

hermes skill create --from SKILL.md

Or copy it to ~/.hermes/skills/devops/tailscale-mcp/SKILL.md.

Architecture

┌─────────────┐     stdio      ┌──────────────┐     subprocess    ┌──────────┐
│ MCP Client   │ ◄──────────► │ mcp-tailscale │ ◄──────────────► │ tailscale │
│ (Hermes,     │               │ (FastMCP)     │                  │ CLI      │
│  Claude, ...)│               │               │                  │          │
└─────────────┘               └──────────────┘                  └──────────┘

All calls are local subprocess wrappers around the tailscale binary. No external API keys, no cloud dependencies.

License

MIT