Tailscale MCP

이미 사용 중인 AI 도구에서 tailnet을 운영하세요. Tailscale MCP는 FastMCP 3.1.0+ 서버로, Tailscale Admin API를 어시스턴트와 자동화 도구에 노출합니다. 장치, DNS, 서비스, 모니터링, Funnel, Taildrop 관련 흐름 등을 소규모 포트만토(portmanteau) 도구 세트를 통해 제공합니다(클라이언트가 수백 개의 작은 도구 이름에 파묻히지 않도록 많은 작업을 통합함). 선택 사항인 SEP-1577 에이전트 워크플로우(run_agentic_tailnet_workflow)를 사용하면 샘플링이 구성되었을 때 유능한 호스트가 다단계 흐름을 실행할 수 있습니다. 선택 사항인 웹 앱(Vite/React)은 인간에게 유리(glass) 스타일의 대시보드를 제공합니다: 내 tailnet 토폴로지, 파트너 tailnet 인사이트, 도움말 및 연결 상태를 확인할 수 있습니다.

저장소: github.com/sandraschi/tailscale-mcp

이 프로젝트의 존재 이유

Tailscale tailnet을 관리한다면 이미 관리자 콘솔과 공식 API를 사용하고 계실 것입니다. 이 프로젝트는 해당 인터페이스를 MCP 도구로 변환하여 Cursor, Claude Desktop, Antigravity 또는 모든 MCP 호환 클라이언트가 임시 셸 스크립트 대신 구조화된 응답(성공 플래그, 오류, 힌트)을 통해 장치를 나열하고, DNS를 검사하며, 자동화를 구동하고, 네트워크에 대한 질문에 답할 수 있도록 합니다.

사용자는 Admin API 계약을 유지합니다: 권위 있는 참조는 여전히 Tailscale API 문서입니다. MCP 서버는 독자적인 그룹화, 특정 흐름에 대한 지속성, 다단계 작업을 위한 선택적 LLM 샘플링, 그리고 빠른 시각적 확인을 위한 선택적 브라우저 UI를 추가합니다.

Related MCP server: mcp-tailscale

제공 기능

MCP 도구 (포트만토 패턴)

수십 개의 일회성 도구 대신, 작업은 manage_tailnet_devices, manage_tailnet_network, monitor_tailnet, manage_taildrop, manage_funnel 등과 같은 동사 중심의 도메인으로 그룹화됩니다(보안, 자동화, 보고, 통합 등). 각 도구는 도구 폭발을 방지하는 다른 플릿 서버와 유사한 정신으로 operation 인수를 취합니다. MCP 이름은 동사가 우선합니다; 이 서버는 Tailscale 전용이므로 중복되는 tailscale_ 접두사는 사용되지 않습니다.

범위에는 장치 및 사용자 관리, MagicDNS 및 네트워크 정책, 노출된 경우의 Tailscale 서비스(TailVIPs), 모니터링 및 메트릭, Funnel 및 Taildrop 관련 흐름(해당되는 경우 CLI 통합 포함), 그리고 파트너와 tailnet을 공유하는 조직을 위한 도움말, 상태, 파트너 tailnet 요약이 포함됩니다.

도구 및 작업의 전체 매트릭스는 **docs/TAILSCALE_MCP_PORTMANTEAU_TOOLS.md**에 있습니다(추가 참조 자료는 문서 색인을 확인하세요).

에이전트 워크플로우 (선택 사항)

다단계 자동화를 위해 **run_agentic_tailnet_workflow**는 FastMCP 샘플링(SEP-1577)을 사용합니다. TAILSCALE_SAMPLING_*을 통해 로컬 OpenAI 호환 엔드포인트(예: Ollama)를 서버에 지정하거나, TAILSCALE_SAMPLING_USE_CLIENT_LLM=1을 사용하여 호스트가 LLM을 실행하도록 할 수 있습니다. 세부 정보 및 안전 주의 사항은 **docs/PRD.md**에 있습니다.

웹 앱 (선택 사항)

web_sota/ 아래의 웹 앱은 어둡고 유리 같은 스타일의 레이아웃을 가진 React/Vite 프런트엔드입니다. 주요 특징:

• 내 tailnet: 네트워크 시각화(get_tailnet_status에서 가져온 Mermaid 토폴로지 및 장식용 Orbit 뷰).

• 파트너 tailnet: 멤버 대 공유 사용자 요약 및 로그인별로 그룹화된 장치( summarize_partner_tailnets 도구와 일치).

• 도움말: 셸에서 연결된 환경 및 샘플링 변수.

이 저장소의 포트는 플릿 인접성 규칙을 따릅니다(기본적으로 프런트엔드 10820 / 백엔드 10821); docs/WEBAPP.md 및 web_sota/start.ps1을 참조하세요.

지속성 및 관측성

DiskStore(FastMCP 3.1.0)는 재시작 시에도 Funnel, 전송 및 기본 설정에 대한 지속적인 상태를 유지합니다. **docs/STORAGE_BACKENDS.md**를 참조하세요. 자체 인프라에서 완전한 관측성을 원할 경우 선택적인 Prometheus / Grafana / Loki 스타일 스택이 docs/monitoring/ 아래에 문서화되어 있습니다.

에이전트를 위한 기술

존재할 경우, **skills/TAILSCALE_EXPERT.md**가 **resource://tailscale/skills**로 노출되어 클라이언트가 도구와 함께 운영자 중심의 지침을 로드할 수 있습니다.

대상 사용자

• tailnet 변경 사항을 IDE 및 자동화에 연결하는 플랫폼 엔지니어.

• 빠른 대시보드와 더 깊은 쿼리를 위한 MCP를 원하는 운영자.

• 일회성 추측 대신 다단계 API 작업을 계획해야 하는 에이전트(적절한 허용 목록 포함).

요구 사항

Tailnet에 대한 액세스 권한이 있는 Tailscale API 키와 키가 범위로 지정된 tailnet 이름이 필요합니다:

샘플링, HTTP 전송 및 로깅을 위한 선택적 변수는 docs/PRD.md 및 **.env.example**에 문서화되어 있습니다.

Tailscale 자체를 처음 접하는 경우, 먼저 **docs/WHAT_IS_TAILSCALE.md**를 읽어보세요. tailnet 대 Admin API 대 클라이언트의 개념을 쉬운 언어로 설명합니다.

설치 (빠른 시작)

전체 옵션(Claude Desktop JSON, Docker, 웹 앱)은 **docs/INSTALL.md**에 있습니다. **uv**를 사용한 최소 경로:

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

시작하기 전에 환경 또는 .env 파일에 TAILSCALE_API_KEY 및 TAILSCALE_TAILNET을 설정하세요.

문서 지도

🛡️ 산업 품질 스택

이 프로젝트는 고충실도 에이전트 오케스트레이션을 위한 SOTA 14.1 산업 표준을 준수합니다:

• Python (코어): 린팅 및 포맷팅을 위한 Ruff. 코어 핸들러 내 print 문에 대한 무관용 원칙(T201).

• 웹 앱 (UI): 밀리초 단위 린팅을 위한 Biome. 엄격한 noConsoleLog 적용.

• 프로토콜 준수: 충돌 방지 JSON-RPC 통신을 보장하기 위한 강화된 stdout/stderr 격리.

• 자동화: 모든 플릿 작업을 위한 Justfile 레시피(just lint, just fix, just dev).

• 보안: bandit 및 safety를 통한 자동화된 감사.

라이선스

MIT - LICENSE를 참조하세요.