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.

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.

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.