Tailscale MCP Server

Integra con la CLI y API de Tailscale para la gestión y monitoreo automatizados de la red.

Documentación

Tailscale MCP Server

Un servidor de Model Context Protocol (MCP) para operar Tailscale desde cualquier cliente MCP. Admite stdio local para clientes de escritorio y un transporte HTTP autenticado para despliegues de tailnet privados. Por defecto, acceso de solo lectura, enlace a localhost y credenciales OAuth de corta duración cuando estén disponibles.

Características

Gestión de dispositivos — listar, autorizar, desautorizar, eliminar, expirar claves, gestionar rutas.
Operaciones de red — conectar/desconectar host, hacer ping a pares, obtener estado y versión de la CLI.
Administración — información del tailnet, uso compartido de archivos, nodos de salida, webhooks, etiquetas de dispositivos, versión del servidor.
ACL y políticas — leer/validar/actualizar ACL, configuración de DNS, claves de autenticación, archivo de políticas, bloqueo de red.
Recursos de solo lectura — resumen del tailnet, lista de dispositivos, detalle por dispositivo, ACL actual.
Prompts — diagnóstico guiado de conectividad y revisión de cambios de ACL.
Herramientas con control de riesgo — niveles read, write y admin mediante TAILSCALE_ALLOWED_TOOL_RISK.
OAuth + clave API — credenciales de cliente OAuth (preferido) o clave API heredada.
Modo HTTP privado — autenticación bearer, validación de Host, límites de tamaño de solicitud, endpoint de verificación de salud.
Soporte Docker — imágenes preconstruidas en Docker Hub y GHCR; despliegue sidecar con Tailscale Serve.

Requisitos

Uno de:

Node.js 20+ — ejecutar mediante npx o instalar globalmente (sin necesidad de runtime adicional).
Bun 1.3+ — utilizado para desarrollo; también funciona como runtime de producción.
Docker — usar la imagen preconstruida (sin runtime local necesario).

Además, un método de autenticación:

Credenciales de cliente OAuth: TAILSCALE_OAUTH_CLIENT_ID + TAILSCALE_OAUTH_CLIENT_SECRET (preferido).
Clave API heredada: TAILSCALE_API_KEY.

La CLI de Tailscale local es opcional. Solo se requiere para herramientas basadas en CLI: get_network_status, connect_network, disconnect_network, ping_peer, get_version y manage_exit_nodes (operaciones de establecer/limpiar).

Inicio Rápido

Claude Desktop

Editar ~/.claude/claude_desktop_config.json (crear si no existe).

Credenciales OAuth (recomendado)

{
  "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": "-"
      }
    }
  }
}

Clave API

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

Habilitar herramientas de escritura/administración

Agregar TAILSCALE_ALLOWED_TOOL_RISK al bloque env:

"TAILSCALE_ALLOWED_TOOL_RISK": "write"

Establecer en "admin" para desbloquear operaciones destructivas (eliminar, desautorizar, conectar/desconectar, mutación de claves).

Docker Hub

{
  "mcpServers": {
    "tailscale": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "TAILSCALE_API_KEY=tskey-api-...",
        "-e", "TAILSCALE_TAILNET=your-tailnet",
        "hexsleeves/tailscale-mcp-server:latest"
      ]
    }
  }
}

Claude Code (CLI)

claude mcp add tailscale \
  -e TAILSCALE_API_KEY=tskey-api-... \
  -e TAILSCALE_TAILNET=- \
  -- npx -y @hexsleeves/tailscale-mcp-server

Con acceso de escritura:

claude mcp add tailscale \
  -e TAILSCALE_API_KEY=tskey-api-... \
  -e TAILSCALE_TAILNET=- \
  -e TAILSCALE_ALLOWED_TOOL_RISK=write \
  -- npx -y @hexsleeves/tailscale-mcp-server

Cursor

Agregar a .cursor/mcp.json (proyecto) o ~/.cursor/mcp.json (global):

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

Referencia de Herramientas

Dispositivos

Herramienta	Descripción	Riesgo mínimo
`list_devices`	Listar todos los dispositivos en el tailnet configurado	`read`
`device_action`	Autorizar o expirar una clave de dispositivo (`write`); desautorizar o eliminar (`admin`)	`write` / `admin`
`manage_routes`	Habilitar o deshabilitar rutas anunciadas para un dispositivo	`write`

Red

Herramienta	Descripción	Riesgo mínimo
`get_network_status`	Obtener el estado actual de la red Tailscale mediante la CLI local	`read`
`connect_network`	Conectar este host a Tailscale con banderas CLI opcionales	`admin`
`disconnect_network`	Desconectar este host de Tailscale	`admin`
`ping_peer`	Hacer ping a un par de Tailscale mediante la CLI local	`read`
`get_version`	Obtener información de versión de la CLI local de Tailscale	`read`

Administración

Herramienta	Descripción	Riesgo mínimo
`get_tailnet_info`	Obtener información detallada sobre el tailnet configurado	`read`
`manage_file_sharing`	Leer (`read`) o actualizar (`write`) la configuración de uso compartido de archivos del tailnet	`read` / `write`
`manage_exit_nodes`	Listar nodos de salida (`read`); establecer, limpiar, anunciar o dejar de anunciar (`admin`)	`read` / `admin`
`manage_webhooks`	Listar webhooks (`read`); crear, eliminar o probar webhooks (`write`)	`read` / `write`
`manage_device_tags`	Leer (`read`) o actualizar (`write`) etiquetas de un dispositivo	`read` / `write`
`get_version_info`	Devolver el identificador de versión del servidor	`read`

ACL y Políticas

Herramienta	Descripción	Riesgo mínimo
`manage_acl`	Leer (`read`), validar o actualizar (`write`) la política ACL del tailnet	`read` / `write`
`manage_dns`	Leer (`read`) o actualizar (`write`) la configuración de DNS de Tailscale	`read` / `write`
`manage_keys`	Listar claves de autenticación (`read`); crear o eliminar (`admin`)	`read` / `admin`
`manage_policy_file`	Leer (`read`) o actualizar (`write`) el archivo de políticas del tailnet	`read` / `write`
`manage_network_lock`	Estado del bloqueo de red (`read`) y operaciones de mutación (`admin`)	`read` / `admin`

Recursos y Prompts

Recursos (solo lectura)

URI	Descripción
`tailscale://tailnet/summary`	Resumen general del tailnet
`tailscale://devices`	Todos los dispositivos en el tailnet
`tailscale://devices/{deviceId}`	Detalle de un solo dispositivo
`tailscale://acl/current`	Política ACL actual

Prompts

Nombre	Descripción
`diagnose_tailnet_connectivity`	Diagnóstico guiado para problemas de conectividad
`review_acl_change`	Flujo de trabajo estructurado de revisión para cambios de política ACL

Configuración

Variable	Predeterminado	Descripción
`TAILSCALE_OAUTH_CLIENT_ID`	—	ID de cliente OAuth (método de autenticación preferido)
`TAILSCALE_OAUTH_CLIENT_SECRET`	—	Secreto de cliente OAuth (requerido con `CLIENT_ID`)
`TAILSCALE_API_KEY`	—	Clave API heredada de respaldo
`TAILSCALE_TAILNET`	`-`	Nombre del tailnet o abreviatura `-` para el tailnet predeterminado
`TAILSCALE_API_BASE_URL`	`https://api.tailscale.com`	URL base de la API de Tailscale (https requerido excepto para localhost)
`TAILSCALE_ALLOWED_TOOL_RISK`	`read`	Riesgo máximo permitido de herramientas: `read`, `write` o `admin`
`TAILSCALE_CLI_PATH`	`tailscale`	Ruta al binario local de la CLI de Tailscale
`MCP_TRANSPORT`	`stdio`	Modo de transporte: `stdio` o `http`
`MCP_HTTP_BIND_HOST`	`127.0.0.1`	Host al que vincular en modo HTTP
`MCP_HTTP_PORT`	`3000`	Puerto al que vincular en modo HTTP
`MCP_HTTP_BEARER_TOKEN`	—	Requerido para modo HTTP (mínimo 32 caracteres)
`MCP_ALLOWED_HOSTS`	—	Valores adicionales permitidos del encabezado HTTP Host, separados por comas
`LOG_LEVEL`	`info`	Verbosidad de registro: `debug`, `info`, `warn` o `error`
`MCP_SERVER_LOG_FILE`	—	Ruta de archivo opcional para salida de registros

Niveles de riesgo

read — listar dispositivos, inspeccionar estado, leer recursos, ejecutar diagnósticos.
write — actualizar ACL, DNS, rutas, archivos de políticas, webhooks, etiquetas y otras configuraciones de mutación.
admin — operaciones destructivas o que afectan al host: eliminar, desautorizar, conectar, desconectar, mutación de claves de autenticación, cambios en uso compartido de archivos, control de nodos de salida.

Transporte HTTP

El modo HTTP está diseñado para acceso privado al tailnet. Requiere MCP_HTTP_BEARER_TOKEN y se vincula a 127.0.0.1 de forma predeterminada.

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="-"

npx -y @hexsleeves/tailscale-mcp-server --http --host 127.0.0.1 --port 3000

Exponer de forma privada con Tailscale Serve (recomendado para despliegues en tailnet):

tailscale serve --bg 443 localhost:3000

No usar Tailscale Funnel para operación normal de MCP. Funnel hace que el endpoint sea accesible públicamente en internet.

Un endpoint GET /health devuelve 200 OK cuando el servidor está en ejecución.

Para instrucciones completas de despliegue sidecar con Docker, consulta docs/docker.md.

Docker

Ejecutar con imagen de Docker Hub

docker run --rm \
  -e TAILSCALE_API_KEY="tskey-api-..." \
  -e TAILSCALE_TAILNET="-" \
  -p 127.0.0.1:3000:3000 \
  hexsleeves/tailscale-mcp-server:latest

Ejecutar con imagen de GHCR

docker run --rm \
  -e TAILSCALE_API_KEY="tskey-api-..." \
  -e TAILSCALE_TAILNET="-" \
  -p 127.0.0.1:3000:3000 \
  ghcr.io/hexsleeves/tailscale-mcp-server:latest

Compilar localmente

docker build -t tailscale-mcp-server .

Para despliegue sidecar con Tailscale Serve, consulta docs/docker.md.

Ejemplos de Prompts

Una vez que el servidor esté conectado a tu cliente MCP, prueba estos:

"Lista mis dispositivos Tailscale y muestra cuáles están sin conexión."
"¿Cuál es el estado actual de la red Tailscale en esta máquina?"
"Diagnostica la conectividad con mi NAS en 100.64.0.5."
"Muéstrame la política ACL actual de mi tailnet."
"Revisa este cambio de ACL antes de aplicarlo." (adjunta la nueva política)
"¿Qué servidores DNS de nombres está usando mi tailnet?"
"Lista todos los webhooks activos en mi tailnet."

Desarrollo

# Install dependencies (Bun required for development)
bun install

# Type check
bun run typecheck

# Run tests
bun test

# Lint and format
bun run check

# Build
bun run build

# Full verification (typecheck + lint + test + build)
bun run qa:full

# Security audit
bun audit

Consulta CONTRIBUTING.md para el flujo de trabajo completo de desarrollo, convenciones de commits y proceso de publicación.

Contribuciones

Las contribuciones son bienvenidas. Por favor, lee CONTRIBUTING.md antes de abrir una solicitud de extracción.

CONTRIBUTING.md — configuración de desarrollo, convenciones de commits, proceso de PR.
SECURITY.md — política de divulgación responsable.
LICENSE — MIT.