Tailscale MCP

Verwalten Sie Ihr Tailnet direkt aus den KI-Tools, die Sie bereits nutzen. Tailscale MCP ist ein FastMCP 3.1.0+-Server, der die Tailscale Admin API für Assistenten und Automatisierung bereitstellt: Geräte, DNS, Dienste, Überwachung, Funnel, Taildrop-bezogene Abläufe und mehr – alles über eine kleine Anzahl an Portmanteau-Tools (viele Operationen pro Tool, damit Ihr Client nicht in hunderten winzigen Tool-Namen untergeht). Optionale SEP-1577 agentische Workflows (run_agentic_tailnet_workflow) ermöglichen es einem fähigen Host, mehrstufige Abläufe auszuführen, wenn Sampling konfiguriert ist. Eine optionale Web-App (Vite/React) bietet Menschen ein Dashboard im Glass-Stil: Mein Tailnet-Topologie, Einblicke in Partner-Tailnets, Hilfe und Verbindungsstatus.

Repository: github.com/sandraschi/tailscale-mcp

Warum existiert dieses Projekt?

Wenn Sie ein Tailscale-Tailnet verwalten, nutzen Sie bereits die Admin-Konsole und die offizielle API. Dieses Projekt verwandelt diese Schnittstelle in MCP-Tools, sodass Cursor, Claude Desktop, Antigravity oder jeder MCP-fähige Client Geräte auflisten, DNS prüfen, Automatisierungen steuern und Fragen zu Ihrem Netzwerk beantworten kann – mit strukturierten Antworten (Erfolgs-Flags, Fehler, Hinweise) anstelle von Ad-hoc-Shell-Skripten.

Sie bleiben beim Vertrag der Admin API: Die maßgebliche Referenz bleibt die Tailscale API-Dokumentation. Der MCP-Server fügt eine meinungsstarke Gruppierung, Persistenz für bestimmte Abläufe, optionales LLM-Sampling für mehrstufige Aufgaben und eine optionale Browser-UI für schnelle visuelle Überprüfungen hinzu.

Related MCP server: mcp-tailscale

Was Sie erhalten

MCP-Tools (Portmanteau-Muster)

Anstatt Dutzender einzelner Tools sind die Operationen in verb-orientierten Domänen gruppiert, wie z. B. manage_tailnet_devices, manage_tailnet_network, monitor_tailnet, manage_taildrop, manage_funnel und mehr (Sicherheit, Automatisierung, Berichterstattung, Integrationen usw.). Jedes Tool akzeptiert ein operation-Argument, ähnlich wie bei anderen Fleet-Servern, die eine Tool-Explosion vermeiden. MCP-Namen sind verb-orientiert; das redundante Präfix tailscale_ wird nicht verwendet, da dieser Server ausschließlich für Tailscale gedacht ist.

Die Abdeckung umfasst Geräte- und Benutzerverwaltung, MagicDNS und Netzwerkrichtlinien, Tailscale-Dienste (TailVIPs) (sofern verfügbar), Überwachung und Metriken, Funnel- und Taildrop-bezogene Abläufe (mit CLI-Integration, wo zutreffend), sowie Hilfe, Status und Zusammenfassungen von Partner-Tailnets für Organisationen, die Tailnets mit Partnern teilen.

Die vollständige Matrix der Tools und Operationen finden Sie unter docs/TAILSCALE_MCP_PORTMANTEAU_TOOLS.md (siehe den Dokumentationsindex für weitere Referenzmaterialien).

Agentische Workflows (optional)

Für mehrstufige Automatisierung nutzt run_agentic_tailnet_workflow das FastMCP-Sampling (SEP-1577). Sie können den Server über TAILSCALE_SAMPLING_* auf einen lokalen OpenAI-kompatiblen Endpunkt (z. B. Ollama) verweisen oder den Host das LLM mit TAILSCALE_SAMPLING_USE_CLIENT_LLM=1 ausführen lassen. Details und Sicherheitshinweise finden Sie unter docs/PRD.md.

Web-App (optional)

Die Web-App unter web_sota/ ist ein React/Vite-Frontend mit einem dunklen Design im Glass-Stil. Highlights:

• Mein Tailnet: Visualisierung Ihres Netzwerks (Mermaid-Topologie von get_tailnet_status sowie eine dekorative Orbit-Ansicht).

• Partner-Tailnets: Zusammenfassung von Mitgliedern vs. geteilten Benutzern und nach Login gruppierten Geräten, abgestimmt auf das Tool summarize_partner_tailnets.

• Hilfe: Umgebungs- und Sampling-Variablen, verlinkt aus der Shell.

Die Ports für dieses Repository folgen der Fleet-Konvention für Adjazenz (standardmäßig 10820 Frontend / 10821 Backend); siehe docs/WEBAPP.md und web_sota/start.ps1.

Persistenz und Observability

DiskStore (FastMCP 3.1.0) speichert dauerhafte Zustände für Funnels, Übertragungen und Einstellungen über Neustarts hinweg – siehe docs/STORAGE_BACKENDS.md. Optionale Stacks im Prometheus / Grafana / Loki-Stil sind unter docs/monitoring/ dokumentiert, falls Sie eine vollständige Observability auf Ihrer eigenen Infrastruktur wünschen.

Fähigkeiten für Agenten

Wenn vorhanden, wird skills/TAILSCALE_EXPERT.md als resource://tailscale/skills bereitgestellt, sodass Clients neben den Tools auch bedienerorientierte Anleitungen laden können.

Für wen ist es gedacht?

• Plattform-Ingenieure, die Tailnet-Änderungen in IDEs und Automatisierungen einbinden.

• Operatoren, die ein schnelles Dashboard sowie MCP für tiefere Abfragen wünschen.

• Agenten (mit entsprechenden Allow-Listen), die mehrstufige API-Arbeiten planen sollen, anstatt nur Einzelschüsse abzugeben.

Anforderungen

Sie benötigen einen Tailscale API-Key mit Zugriff auf Ihr Tailnet und den Tailnet-Namen, für den der Key gültig ist:

Optionale Variablen für Sampling, HTTP-Transport und Logging sind in docs/PRD.md und .env.example dokumentiert.

Wenn Sie neu bei Tailscale sind, lesen Sie zuerst docs/WHAT_IS_TAILSCALE.md – dort werden Tailnet vs. Admin API vs. Client in einfacher Sprache erklärt.

Installation (schnell)

Alle Optionen (Claude Desktop JSON, Docker, Web-App) finden Sie unter docs/INSTALL.md. Minimaler Pfad mit uv:

git clone https://github.com/sandraschi/tailscale-mcp.git
cd tailscale-mcp
uv sync
uv run tailscale-mcp

Setzen Sie TAILSCALE_API_KEY und TAILSCALE_TAILNET in Ihrer Umgebung oder .env, bevor Sie starten.

Dokumentationsübersicht

🛡️ Industrieller Qualitäts-Stack

Dieses Projekt hält sich an die SOTA 14.1 Industriestandards für hochpräzise agentische Orchestrierung:

• Python (Core): Ruff für Linting und Formatierung. Null-Toleranz für print-Anweisungen in Core-Handlern (T201).

• Web-App (UI): Biome für Linting im Sub-Millisekundenbereich. Strenge Durchsetzung von noConsoleLog.

• Protokoll-Konformität: Gehärtete stdout/stderr-Isolierung zur Gewährleistung einer absturzsicheren JSON-RPC-Kommunikation.

• Automatisierung: Justfile-Rezepte für alle Fleet-Operationen (just lint, just fix, just dev).

• Sicherheit: Automatisierte Audits via bandit und safety.

Lizenz

MIT – siehe LICENSE.