Content
# 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
