# 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

```bash
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`:

```yaml
mcp_servers:
  tailscale:
    command: "mcp-tailscale"
```

Restart Hermes. Tools appear as `mcp_tailscale_*`.

### Claude Desktop

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

### VS Code / Cline / Continue

```json
{
  "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

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

Test the server starts correctly:

```bash
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:

```bash
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