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
HashiCorp Vault Integration (Optional)
mcp-tailscale supports opportunistic secret loading from HashiCorp Vault via AppRole authentication. This lets you store your Tailscale credentials centrally in Vault and avoid passing sensitive values through MCP config files or shell environment variables.
How It Works
At startup, the server checks whether NAS_VAULT_ADDR is set. If it is, it authenticates to Vault using AppRole credentials, reads the KV v2 secret at <mount>/data/tailscale/api, and injects the values into the process environment before the Tailscale client is initialized.
- Opportunistic loading — if
NAS_VAULT_ADDRis unset, the Vault loader is a silent no-op. The server behaves exactly as without Vault. - Silent fallback — if Vault is unreachable, authentication fails, or the secret path is missing, a single-line warning is written to stderr and the server falls back to whatever environment variables are already set.
- No new runtime dependencies — the loader uses the global
fetchavailable in Node.js 20+ (no extra packages). - Secret values are never logged — only the KV path name and a populated-count appear in stderr diagnostics.
Precedence
Explicit env vars > Vault > error (missing credentials)
If TAILSCALE_API_KEY is already set in the environment, Vault is still contacted (if configured) but the explicit value wins. This lets you override Vault values per-session without touching the Vault secret.
Vault Environment Variables
| Variable | Required | Description |
|---|---|---|
NAS_VAULT_ADDR | Yes* | Vault server address (e.g., https://vault.example.com:8200) |
NAS_VAULT_ROLE_ID | Yes* | AppRole role ID for this server |
NAS_VAULT_SECRET_ID | Yes* | AppRole secret ID for this server |
NAS_VAULT_KV_MOUNT | No | KV v2 mount path (default: kv) |
* Only required if using Vault. When NAS_VAULT_ADDR is unset, none of these are read.
KV v2 Secret Structure
The loader reads the secret at path <mount>/data/tailscale/api (default: kv/data/tailscale/api) and maps keys as follows:
# Path: kv/tailscale/api
{
"api_key": "tskey-api-your-key",
"tailnet": "your-tailnet.ts.net"
}
| Vault Key | Maps To |
|---|---|
api_key | TAILSCALE_API_KEY |
tailnet | TAILSCALE_TAILNET |
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.
Vault Setup Steps
1. Write the Tailscale credentials to KV v2:
vault kv put kv/tailscale/api \
api_key="tskey-api-your-key" \
tailnet="your-tailnet.ts.net"
2. Create a Vault policy:
# tailscale-mcp-policy.hcl
path "kv/data/tailscale/api" {
capabilities = ["read"]
}
vault policy write tailscale-mcp tailscale-mcp-policy.hcl
3. Enable AppRole auth and create a role:
vault auth enable approle
vault write auth/approle/role/tailscale-mcp \
token_policies="tailscale-mcp" \
token_ttl="1h" \
token_max_ttl="4h"
4. Retrieve the role ID and generate a secret ID:
vault read auth/approle/role/tailscale-mcp/role-id
vault write -f auth/approle/role/tailscale-mcp/secret-id
MCP Config Example (with Vault)
{
"mcpServers": {
"tailscale": {
"command": "npx",
"args": ["@itunified.io/mcp-tailscale"],
"env": {
"NAS_VAULT_ADDR": "https://vault.example.com:8200",
"NAS_VAULT_ROLE_ID": "your-role-id",
"NAS_VAULT_SECRET_ID": "your-secret-id"
}
}
}
}
With this configuration, no Tailscale credentials appear in the MCP config — they are fetched from Vault at startup.
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.