Tailscale MCP Server

Integre com a CLI e a API do Tailscale para gerenciamento e monitoramento automatizados de rede.

Documentação

Tailscale MCP Server

Um servidor Model Context Protocol (MCP) para operar o Tailscale a partir de qualquer cliente MCP. Suporta stdio local para clientes desktop e um transporte HTTP autenticado para implantações em tailnet privado. O padrão é acesso somente leitura, vinculação a localhost e credenciais OAuth de curta duração quando disponíveis.

Recursos

Gerenciamento de dispositivos — listar, autorizar, desautorizar, excluir, expirar chaves, gerenciar rotas.
Operações de rede — conectar/desconectar host, ping em peers, obter status e versão da CLI.
Administração — informações do tailnet, compartilhamento de arquivos, nós de saída, webhooks, tags de dispositivos, versão do servidor.
ACL e políticas — ler/validar/atualizar ACL, configurações de DNS, chaves de autenticação, arquivo de políticas, network lock.
Recursos somente leitura — resumo do tailnet, lista de dispositivos, detalhes por dispositivo, ACL atual.
Prompts — diagnóstico guiado de conectividade e revisão de alterações de ACL.
Ferramentas com níveis de risco — níveis read, write e admin via TAILSCALE_ALLOWED_TOOL_RISK.
OAuth + chave de API — credenciais de cliente OAuth (preferencial) ou chave de API legada.
Modo HTTP privado — autenticação bearer, validação de Host, limites de tamanho de requisição, endpoint de health check.
Suporte a Docker — imagens pré-construídas no Docker Hub e GHCR; implantação sidecar com Tailscale Serve.

Requisitos

Um dos seguintes:

Node.js 20+ — execute via npx ou instale globalmente (sem necessidade de runtime adicional).
Bun 1.3+ — usado para desenvolvimento; também funciona como runtime de produção.
Docker — use a imagem pré-construída (sem necessidade de runtime local).

Além de um método de autenticação:

Credenciais de cliente OAuth: TAILSCALE_OAUTH_CLIENT_ID + TAILSCALE_OAUTH_CLIENT_SECRET (preferencial).
Chave de API legada: TAILSCALE_API_KEY.

A CLI do Tailscale local é opcional. Ela é necessária apenas para ferramentas baseadas em CLI: get_network_status, connect_network, disconnect_network, ping_peer, get_version e manage_exit_nodes (operações de definir/limpar).

Início Rápido

Claude Desktop

Edite ~/.claude/claude_desktop_config.json (crie se não existir).

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

Chave de API

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

Habilitar ferramentas de escrita/administração

Adicione TAILSCALE_ALLOWED_TOOL_RISK ao bloco env:

"TAILSCALE_ALLOWED_TOOL_RISK": "write"

Defina como "admin" para desbloquear operações destrutivas (excluir, desautorizar, conectar/desconectar, mutação de chaves).

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

Com acesso de escrita:

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

Adicione a .cursor/mcp.json (projeto) ou ~/.cursor/mcp.json (global):

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

Referência de Ferramentas

Dispositivos

Ferramenta	Descrição	Risco mínimo
`list_devices`	Lista todos os dispositivos no tailnet configurado	`read`
`device_action`	Autoriza ou expira a chave de um dispositivo (`write`); desautoriza ou exclui (`admin`)	`write` / `admin`
`manage_routes`	Habilita ou desabilita rotas anunciadas para um dispositivo	`write`

Rede

Ferramenta	Descrição	Risco mínimo
`get_network_status`	Obtém o status atual da rede Tailscale via CLI local	`read`
`connect_network`	Conecta este host ao Tailscale com flags opcionais da CLI	`admin`
`disconnect_network`	Desconecta este host do Tailscale	`admin`
`ping_peer`	Envia ping para um peer do Tailscale via CLI local	`read`
`get_version`	Obtém informações de versão da CLI local do Tailscale	`read`

Administração

Ferramenta	Descrição	Risco mínimo
`get_tailnet_info`	Obtém informações detalhadas sobre o tailnet configurado	`read`
`manage_file_sharing`	Lê (`read`) ou atualiza (`write`) as configurações de compartilhamento de arquivos do tailnet	`read` / `write`
`manage_exit_nodes`	Lista nós de saída (`read`); define, limpa, anuncia ou para de anunciar (`admin`)	`read` / `admin`
`manage_webhooks`	Lista webhooks (`read`); cria, exclui ou testa webhooks (`write`)	`read` / `write`
`manage_device_tags`	Lê (`read`) ou atualiza (`write`) tags de um dispositivo	`read` / `write`
`get_version_info`	Retorna o identificador de versão do servidor	`read`

ACL e Políticas

Ferramenta	Descrição	Risco mínimo
`manage_acl`	Lê (`read`), valida ou atualiza (`write`) a política de ACL do tailnet	`read` / `write`
`manage_dns`	Lê (`read`) ou atualiza (`write`) as configurações de DNS do Tailscale	`read` / `write`
`manage_keys`	Lista chaves de autenticação (`read`); cria ou exclui (`admin`)	`read` / `admin`
`manage_policy_file`	Lê (`read`) ou atualiza (`write`) o arquivo de políticas do tailnet	`read` / `write`
`manage_network_lock`	Status do network lock (`read`) e operações de mutação (`admin`)	`read` / `admin`

Recursos e Prompts

Recursos (somente leitura)

URI	Descrição
`tailscale://tailnet/summary`	Resumo de alto nível do tailnet
`tailscale://devices`	Todos os dispositivos no tailnet
`tailscale://devices/{deviceId}`	Detalhes de um único dispositivo
`tailscale://acl/current`	Política de ACL atual

Prompts

Nome	Descrição
`diagnose_tailnet_connectivity`	Diagnóstico guiado para problemas de conectividade
`review_acl_change`	Fluxo de trabalho estruturado de revisão para alterações de política de ACL

Configuração

Variável	Padrão	Descrição
`TAILSCALE_OAUTH_CLIENT_ID`	—	ID do cliente OAuth (método de autenticação preferencial)
`TAILSCALE_OAUTH_CLIENT_SECRET`	—	Segredo do cliente OAuth (obrigatório com `CLIENT_ID`)
`TAILSCALE_API_KEY`	—	Chave de API legada como fallback
`TAILSCALE_TAILNET`	`-`	Nome do tailnet ou abreviação `-` para o tailnet padrão
`TAILSCALE_API_BASE_URL`	`https://api.tailscale.com`	URL base da API do Tailscale (https obrigatório, exceto para localhost)
`TAILSCALE_ALLOWED_TOOL_RISK`	`read`	Risco máximo permitido para ferramentas: `read`, `write` ou `admin`
`TAILSCALE_CLI_PATH`	`tailscale`	Caminho para o binário da CLI local do Tailscale
`MCP_TRANSPORT`	`stdio`	Modo de transporte: `stdio` ou `http`
`MCP_HTTP_BIND_HOST`	`127.0.0.1`	Host para vincular no modo HTTP
`MCP_HTTP_PORT`	`3000`	Porta para vincular no modo HTTP
`MCP_HTTP_BEARER_TOKEN`	—	Obrigatório para o modo HTTP (mínimo de 32 caracteres)
`MCP_ALLOWED_HOSTS`	—	Valores adicionais permitidos para o cabeçalho HTTP Host, separados por vírgula
`LOG_LEVEL`	`info`	Nível de verbosidade do log: `debug`, `info`, `warn` ou `error`
`MCP_SERVER_LOG_FILE`	—	Caminho opcional de arquivo para saída de log

Níveis de risco

read — listar dispositivos, inspecionar status, ler recursos, executar diagnósticos.
write — atualizar ACLs, DNS, rotas, arquivos de políticas, webhooks, tags e outras configurações mutáveis.
admin — operações destrutivas ou que afetam o host: excluir, desautorizar, conectar, desconectar, mutação de chaves de autenticação, alterações de compartilhamento de arquivos, controle de nós de saída.

Transporte HTTP

O modo HTTP é destinado ao acesso privado ao tailnet. Ele requer MCP_HTTP_BEARER_TOKEN e vincula a 127.0.0.1 por padrão.

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

Exponha de forma privada com Tailscale Serve (recomendado para implantações em tailnet):

tailscale serve --bg 443 localhost:3000

Não use Tailscale Funnel para operação normal do MCP. O Funnel torna o endpoint publicamente acessível na internet.

Um endpoint GET /health retorna 200 OK quando o servidor está em execução.

Para instruções completas de implantação sidecar com Docker, consulte docs/docker.md.

Docker

Executar com imagem do 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

Executar com imagem 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 implantação sidecar com Tailscale Serve, consulte docs/docker.md.

Exemplos de Prompts

Depois que o servidor estiver conectado ao seu cliente MCP, experimente estes:

"Liste meus dispositivos Tailscale e mostre quais estão offline."
"Qual é o status atual da rede Tailscale nesta máquina?"
"Diagnostique a conectividade com meu NAS em 100.64.0.5."
"Mostre-me a política de ACL atual do meu tailnet."
"Revise esta alteração de ACL antes de eu aplicá-la." (anexe a nova política)
"Quais servidores DNS meu tailnet está usando?"
"Liste todos os webhooks ativos no meu tailnet."

Desenvolvimento

# 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

Consulte CONTRIBUTING.md para o fluxo de trabalho completo de desenvolvimento, convenções de commit e processo de release.

Contribuição

Contribuições são bem-vindas. Por favor, leia CONTRIBUTING.md antes de abrir um pull request.

CONTRIBUTING.md — configuração de desenvolvimento, convenções de commit, processo de PR.
SECURITY.md — política de divulgação responsável.
LICENSE — MIT.