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_ADDR is 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 fetch available 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

* 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"
}

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.

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

*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)

DNS (8 tools)

ACL (5 tools)

Keys (4 tools)

Tailnet (5 tools)

Users (2 tools)

Webhooks (4 tools)

Posture Integrations (4 tools)

Diagnostics (5 tools)

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.