tailscale-mcp

mcp-tailscale

Secure MCP access for private infrastructure over Tailscale

The Problem

AI agents need access to internal tools, services, and infrastructure — but exposing private systems to the internet creates unacceptable security risks. VPNs are complex, SSH tunnels are fragile, and API gateways add latency and maintenance overhead.

mcp-tailscale bridges this gap: a lightweight MCP server that gives AI agents secure, authenticated access to your Tailscale-connected infrastructure — without exposing anything to the public internet.

What It Does

mcp-tailscale is an MCP Gateway Runtime that connects AI agents (Claude, GPT, custom) to your private infrastructure through Tailscale's zero-trust network. It provides 48 tools across 9 domains for managing devices, DNS, ACL policies, auth keys, users, webhooks, posture integrations, and tailnet settings — all through the Tailscale API v2.

No SSH. No shell execution. API-only. 4 runtime dependencies.

Use Cases

• DevOps Automation — Let AI agents manage device authorization, subnet routes, and ACL policies across your tailnet
• DNS Management — Configure split DNS, global nameservers, and MagicDNS through natural language
• Security Auditing — Automated ACL policy validation, posture compliance checks, and key rotation
• Fleet Management — Monitor device status, manage tags, and onboard new devices at scale
• Infrastructure as Conversation — Query and modify your private network configuration through AI-driven workflows

Quick Start

Install from npm

npm install -g tailscale-mcp

Or clone and build from source

git clone https://github.com/itunified-io/mcp-tailscale.git
cd mcp-tailscale
npm install
cp .env.example .env   # Edit with your Tailscale API key and tailnet name
npm run build
node dist/index.js     # stdio transport for MCP

Claude Code Integration

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "tailscale": {
      "command": "node",
      "args": ["/path/to/mcp-tailscale/dist/index.js"],
      "env": {
        "TAILSCALE_API_KEY": "your-api-key-here",
        "TAILSCALE_TAILNET": "your-tailnet-name"
      },
      "comment": "Or use OAuth: TAILSCALE_OAUTH_CLIENT_ID + TAILSCALE_OAUTH_CLIENT_SECRET instead of TAILSCALE_API_KEY"
    }
  }
}

Features

48 tools across 9 domains:

• Devices — List, get, delete, authorize, expire, rename devices; manage routes, tags, and posture attributes
• DNS — Global nameservers, search paths, split DNS configuration, MagicDNS preferences
• ACL — Get, set, preview, validate, and test ACL policies
• Keys — List, get, create, and revoke auth keys
• Tailnet — Settings (read/write), contacts, Tailnet Lock status
• Users — List and get tailnet users with role/type filtering
• Webhooks — Create, list, get, and delete webhook endpoints
• Posture Integrations — List, get, create, and delete third-party posture provider integrations
• Diagnostics — Tailnet status summary, API connectivity check, log streaming, DERP map

Authentication: API key or OAuth client credentials (auto-refresh)

Skills

Claude Code skills compose MCP tools into higher-level workflows. See .claude/skills/README.md for detailed documentation.

Skill	Slash Command	Description
tailscale-health	/ts-health	Tailnet health dashboard — devices, DNS, ACL, keys, connectivity
tailscale-live-test	/ts-test	Live integration test — read + safe writes with cleanup
tailscale-acl-management	—	ACL policy management — view, edit, validate, test, drift detection
tailscale-device-management	—	Device management — list, authorize, routes, tags, posture
tailscale-dns-management	—	DNS management — split DNS, nameservers, search paths, MagicDNS
tailscale-key-management	—	Auth key management — create, list, rotate, revoke
tailscale-onboarding	—	New device onboarding — auth key, authorize, tags, routes, verify

SSE Transport

By default, mcp-tailscale uses stdio transport. To enable HTTP/SSE:

export TAILSCALE_MCP_TRANSPORT=sse
export TAILSCALE_MCP_AUTH_TOKEN=your-secret-token
export TAILSCALE_MCP_PORT=3000      # optional, default: 3000
export TAILSCALE_MCP_HOST=localhost  # optional, default: localhost
node dist/index.js

All requests require Authorization: Bearer <token>. The server will not start without TAILSCALE_MCP_AUTH_TOKEN.

Configuration

Variable	Required	Default	Description
TAILSCALE_API_KEY	Yes*	—	Tailscale API key (from admin console > Settings > Keys)
TAILSCALE_OAUTH_CLIENT_ID	Yes*	—	OAuth client ID (from admin console > Settings > OAuth)
TAILSCALE_OAUTH_CLIENT_SECRET	Yes*	—	OAuth client secret
TAILSCALE_TAILNET	Yes	—	Tailnet name (e.g., example.com or your org name)
TAILSCALE_API_URL	No	https://api.tailscale.com	API base URL (override for testing)
TAILSCALE_TIMEOUT	No	30000	Request timeout in milliseconds
NAS_VAULT_ADDR	No	—	HashiCorp Vault URL, enables Vault AppRole loading (see below)
NAS_VAULT_ROLE_ID	No	—	Vault AppRole role_id
NAS_VAULT_SECRET_ID	No	—	Vault AppRole secret_id
NAS_VAULT_KV_MOUNT	No	kv	Vault KV v2 mount path

*Either TAILSCALE_API_KEY or both TAILSCALE_OAUTH_CLIENT_ID + TAILSCALE_OAUTH_CLIENT_SECRET must be set. OAuth takes priority when both are configured.

Loading Secrets from HashiCorp Vault (AppRole)

If you run a central Vault instance, mcp-tailscale can fetch its credentials at startup via AppRole instead of passing them through the MCP config:

export NAS_VAULT_ADDR=https://vault.example.com
export NAS_VAULT_ROLE_ID=<role-id>
export NAS_VAULT_SECRET_ID=<secret-id>
# optional — defaults to "kv"
export NAS_VAULT_KV_MOUNT=kv

The loader reads KV v2 at <mount>/data/tailscale/api and expects two keys: api_key and tailnet. Example Vault write:

vault kv put kv/tailscale/api \
  api_key=tskey-api-test \
  tailnet=your-tailnet-name

Precedence: process.env (explicit) > Vault. If NAS_VAULT_ADDR is unset the loader is a silent no-op — the server behaves exactly as before. On any Vault error (network, auth, missing path), a single-line warning is written to stderr and the server falls back to whatever env vars are already set.

OAuth note: the Vault loader only handles the API-key path. If you use OAuth (TAILSCALE_OAUTH_CLIENT_ID / TAILSCALE_OAUTH_CLIENT_SECRET), set those through the normal environment — they are not currently read from Vault.

Security: secret values are never logged. Only the KV path name and a populated-count appear in stderr diagnostics. Uses the global fetch (Node 20+) — no new runtime dependencies.

Authentication

API Key: Create at login.tailscale.com/admin/settings/keys. The key needs read/write access to the resources you want to manage.

OAuth Client Credentials: Create at login.tailscale.com/admin/settings/oauth. OAuth tokens auto-refresh before expiry. Recommended for automated/service integrations.

Tools

Devices (11 tools)

Tool	Description
tailscale_device_list	List all devices in the tailnet
tailscale_device_get	Get device details by ID
tailscale_device_delete	Delete a device (requires confirm: true)
tailscale_device_authorize	Authorize a pending device
tailscale_device_routes_get	Get advertised and enabled routes
tailscale_device_routes_set	Set enabled subnet routes
tailscale_device_tags_set	Set ACL tags on a device
tailscale_device_posture_get	Get custom posture attributes
tailscale_device_posture_set	Set a custom posture attribute
tailscale_device_expire	Expire a device key (requires confirm: true)
tailscale_device_rename	Set a custom display name for a device

DNS (8 tools)

Tool	Description
tailscale_dns_nameservers_get	Get global DNS nameservers
tailscale_dns_nameservers_set	Set global DNS nameservers
tailscale_dns_searchpaths_get	Get DNS search paths
tailscale_dns_searchpaths_set	Set DNS search paths
tailscale_dns_splitdns_get	Get split DNS configuration
tailscale_dns_splitdns_set	Update split DNS configuration (PATCH)
tailscale_dns_preferences_get	Get DNS preferences (MagicDNS)
tailscale_dns_preferences_set	Set DNS preferences

ACL (5 tools)

Tool	Description
tailscale_acl_get	Get the current ACL policy
tailscale_acl_set	Replace the ACL policy (requires confirm: true)
tailscale_acl_preview	Preview ACL policy for a user or IP
tailscale_acl_validate	Validate an ACL policy without applying
tailscale_acl_test	Run ACL tests defined in the policy

Keys (4 tools)

Tool	Description
tailscale_key_list	List all auth keys
tailscale_key_get	Get auth key details
tailscale_key_create	Create a new auth key
tailscale_key_delete	Delete an auth key (requires confirm: true)

Tailnet (5 tools)

Tool	Description
tailscale_tailnet_settings_get	Get tailnet settings
tailscale_tailnet_settings_update	Update tailnet settings (requires confirm: true)
tailscale_tailnet_contacts_get	Get tailnet contact emails
tailscale_tailnet_contacts_set	Update tailnet contacts (requires confirm: true)
tailscale_tailnet_lock_status	Get Tailnet Lock status

Users (2 tools)

Tool	Description
tailscale_user_list	List all users (filter by type/role)
tailscale_user_get	Get user details by ID

Webhooks (4 tools)

Tool	Description
tailscale_webhook_list	List all webhook endpoints
tailscale_webhook_create	Create a webhook endpoint
tailscale_webhook_get	Get webhook details by ID
tailscale_webhook_delete	Delete a webhook (requires confirm: true)

Posture Integrations (4 tools)

Tool	Description
tailscale_posture_integration_list	List all posture provider integrations
tailscale_posture_integration_get	Get posture integration details by ID
tailscale_posture_integration_create	Create a posture provider integration
tailscale_posture_integration_delete	Delete a posture integration (requires confirm: true)

Diagnostics (5 tools)

Tool	Description
tailscale_status	Tailnet status summary (device counts, online/offline)
tailscale_api_verify	Verify API connectivity and authentication
tailscale_log_stream_get	Get log streaming configuration
tailscale_log_stream_set	Set log streaming configuration (requires confirm: true)
tailscale_derp_map	Get DERP relay map

Architecture

See ARCHITECTURE.md for detailed architecture diagrams and component descriptions.

Roadmap

See ROADMAP.md for the product development roadmap.

Development

npm run build      # Compile TypeScript
npm test           # Run unit tests (vitest)
npm run typecheck  # Type check only (no emit)

See CONTRIBUTING.md for contribution guidelines. See docs/api-reference.md for the Tailscale API v2 endpoint mapping.

Open Source

mcp-tailscale is the community edition — a fully functional MCP Gateway Runtime under AGPL-3.0. Self-host it, contribute to it, build on it.

What you get with the open-source edition:

• Complete Tailscale API v2 coverage (48 tools, 9 domains)
• stdio and SSE transport
• API key and OAuth authentication
• Zod-validated inputs, structured error handling
• Claude Code skills for common workflows
• Full test suite (vitest)

Commercial

For organizations that need governance, compliance, and multi-tenant capabilities on top of the open-source runtime, we offer commercial editions with enterprise features.

Planned enterprise capabilities:

• Role-based access control (RBAC)
• OIDC/SAML single sign-on
• Audit event logging
• Policy engine for tool access control
• Multi-tenant isolation
• Commercial license (no AGPL obligations)
• Priority support and SLA

See PRODUCT_PACKAGING.md for tier details.

Contact us: GitHub Sponsors

License

This project is dual-licensed:

• Open Source: GNU Affero General Public License v3.0 (AGPL-3.0) — free for open-source and non-commercial use
• Commercial: Available for proprietary integrations — see COMMERCIAL_LICENSE.md

If you use mcp-tailscale in a proprietary product or SaaS offering, a commercial license is required. Support development by sponsoring us on GitHub.