Tailscale MCP Server

An MCP (Model Context Protocol) server for managing Tailscale resources using the official Tailscale Go client library v2. This server provides complete coverage of the Tailscale API with enhanced, self-descriptive tools powered by OpenAPI documentation.

🚀 Features

This MCP server provides 42 comprehensive tools organized into logical categories, each with detailed descriptions, OAuth scopes, use cases, and security considerations:

🖥️ Device Management (9 tools)

tailscale_devices_list - List all devices with optional detailed fields
tailscale_device_get - Get comprehensive device information
tailscale_device_delete - Permanently remove devices from tailnet
tailscale_device_authorize - Authorize/deauthorize devices for access control
tailscale_device_set_name - Set device names (affects Magic DNS)
tailscale_device_set_tags - Assign tags for ACL-based access control
tailscale_device_expire - Force device re-authentication
tailscale_device_routes_list - List subnet routes and exit node configuration
tailscale_device_routes_set - Configure subnet routing and exit nodes

🔐 Key Management (4 tools)

tailscale_keys_list - List all authentication keys with capabilities
tailscale_key_get - Get detailed key information and usage statistics
tailscale_key_create - Create reusable, ephemeral, or preauthorized keys
tailscale_key_delete - Revoke authentication keys

👥 User Management (8 tools)

tailscale_users_list - List all users with roles and status
tailscale_user_get - Get detailed user profile information
tailscale_user_approve - Approve users for tailnet access
tailscale_user_suspend - Temporarily suspend user access
tailscale_user_restore - Restore suspended users
tailscale_user_delete - Permanently remove users
tailscale_contacts_get - Get tailnet contact preferences
tailscale_contact_update - Update contact information for notifications

🌐 DNS Management (9 tools)

tailscale_dns_nameservers_get - Get configured DNS nameservers
tailscale_dns_nameservers_set - Set custom DNS nameservers
tailscale_dns_preferences_get - Get MagicDNS and DNS preferences
tailscale_dns_preferences_set - Configure MagicDNS and DNS behavior
tailscale_dns_searchpaths_get - Get DNS search domain suffixes
tailscale_dns_searchpaths_set - Set DNS search paths for short names
tailscale_policy_get - Get current ACL policy file (HuJSON)
tailscale_policy_set - Update ACL policy with security rules
tailscale_policy_validate - Validate policy files before deployment

🔗 Advanced Features (12 tools)

tailscale_webhooks_list - List webhook endpoints for event notifications
tailscale_webhook_create - Create webhooks for external integrations
tailscale_webhook_get - Get webhook configuration and statistics
tailscale_webhook_delete - Remove webhook endpoints
tailscale_logging_configuration_get - Get audit log streaming configuration
tailscale_logging_network_get - Get network flow log configuration
tailscale_device_posture_integrations_list - List security posture integrations
tailscale_device_posture_integration_create - Create posture provider integrations
tailscale_device_posture_integration_get - Get posture integration details
tailscale_device_posture_integration_delete - Remove posture integrations
tailscale_tailnet_settings_get - Get comprehensive tailnet settings
tailscale_tailnet_settings_update - Update tailnet configuration

📦 Installation

Prerequisites

Valid Tailscale account with API access
Tailscale API key or OAuth client credentials
Choose one deployment method:
- Docker (recommended) - Docker and Docker Compose
- Binary - Go 1.24 or later
- Source - Go 1.24 or later + Git

🐳 Docker Deployment (Recommended)

The easiest way to run the Tailscale MCP server is using Docker:

Quick Start with Docker

# Using API key authentication
docker run -d \
  --name tailscale-mcp-server \
  --restart unless-stopped \
  -e TAILSCALE_API_KEY="tskey-api-..." \
  -e TAILSCALE_TAILNET="your-tailnet" \
  tailscale-mcp-server:latest

# Using OAuth authentication
docker run -d \
  --name tailscale-mcp-server \
  --restart unless-stopped \
  -e TAILSCALE_CLIENT_ID="your-client-id" \
  -e TAILSCALE_CLIENT_SECRET="your-client-secret" \
  -e TAILSCALE_TAILNET="your-tailnet" \
  tailscale-mcp-server:latest

Docker Compose (Recommended)

Clone the repository:

git clone <repository-url>
cd mcp

Create environment file:

# Copy example environment file
cp .env.example .env

# Edit with your credentials
vim .env

Start the server:

# Build and start
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the server
docker-compose down

Building Docker Image Locally

# Build the image
docker build -t tailscale-mcp-server:local .

# Run with local image
docker run -d \
  --name tailscale-mcp-server \
  -e TAILSCALE_API_KEY="tskey-api-..." \
  tailscale-mcp-server:local

Build from Source

Clone the repository and navigate to the MCP directory:

git clone <repository-url>
cd mcp

Install dependencies:

go mod tidy

Build the server:

go build -o tailscale-mcp-server ./cmd

Binary Installation

# Download and install directly
go install github.com/pnocera/tailscale-mcp-server/cmd@latest

⚙️ Configuration

The server supports both API key and OAuth authentication methods for maximum flexibility.

Environment Variables

API Key Authentication (Recommended for personal use)

export TAILSCALE_API_KEY="tskey-api-..."
export TAILSCALE_TAILNET="your-tailnet-name"  # Optional, defaults to "-"

OAuth Authentication (Recommended for applications)

export TAILSCALE_CLIENT_ID="your-oauth-client-id"
export TAILSCALE_CLIENT_SECRET="your-oauth-client-secret"
export TAILSCALE_TAILNET="your-tailnet-name"  # Optional, defaults to "-"

Authentication Priority

If both TAILSCALE_CLIENT_ID and TAILSCALE_CLIENT_SECRET are set, OAuth is used
Otherwise, API key authentication is used with TAILSCALE_API_KEY

🚀 Usage

Running the Server

# Using API key authentication
TAILSCALE_API_KEY="tskey-api-..." ./tailscale-mcp-server

# Using OAuth authentication
TAILSCALE_CLIENT_ID="..." TAILSCALE_CLIENT_SECRET="..." ./tailscale-mcp-server

# With custom tailnet
TAILSCALE_API_KEY="tskey-api-..." TAILSCALE_TAILNET="mycompany.com" ./tailscale-mcp-server

MCP Client Integration

Claude Code Integration

With Docker:

# Add Docker container to Claude Code
claude mcp add tailscale docker run --rm -i \
  -e TAILSCALE_API_KEY="tskey-api-..." \
  tailscale-mcp-server:latest

With Binary:

# Add binary to Claude Code
claude mcp add tailscale /path/to/tailscale-mcp-server

Generic MCP Client Configuration

With Docker:

{
  "mcpServers": {
    "tailscale": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "TAILSCALE_API_KEY=tskey-api-...",
        "-e", "TAILSCALE_TAILNET=your-tailnet",
        "tailscale-mcp-server:latest"
      ]
    }
  }
}

With Binary:

{
  "mcpServers": {
    "tailscale": {
      "command": "/path/to/tailscale-mcp-server",
      "env": {
        "TAILSCALE_API_KEY": "tskey-api-...",
        "TAILSCALE_TAILNET": "your-tailnet"
      }
    }
  }
}

🚀 Quick Deployment Scripts

Instant Setup:

# Bash/Linux/macOS - Quick run with environment validation
./scripts/quick-run.sh

# PowerShell/Windows - Quick run with environment validation
.\scripts\quick-run.ps1

# Custom image
./scripts/quick-run.sh ghcr.io/myuser/tailscale-mcp-server:v1.0.0

Registry Publishing:

# Bash - Build and push to registry
./scripts/build-and-push.sh
./scripts/build-and-push.sh ghcr.io/myuser v1.0.0
./scripts/build-and-push.sh docker.io/myuser latest linux/amd64

# PowerShell - Build and push to registry
.\scripts\build-and-push.ps1
.\scripts\build-and-push.ps1 -Registry "ghcr.io/myuser" -Tag "v1.0.0"
.\scripts\build-and-push.ps1 -Registry "docker.io/myuser" -Platform "linux/amd64"

Docker Container Management

# Check container status
docker ps | grep tailscale-mcp-server

# View container logs
docker logs tailscale-mcp-server

# Restart container
docker restart tailscale-mcp-server

# Update to latest image
docker pull tailscale-mcp-server:latest
docker stop tailscale-mcp-server
docker rm tailscale-mcp-server
# Then run with new image

📚 Tool Examples

Device Management

// List all devices with detailed information
{
  "name": "tailscale_devices_list",
  "arguments": {
    "fields": "all"
  }
}

// Get specific device details
{
  "name": "tailscale_device_get",
  "arguments": {
    "device_id": "device-id-here",
    "fields": "all"
  }
}

// Authorize a device
{
  "name": "tailscale_device_authorize",
  "arguments": {
    "device_id": "device-id-here",
    "authorized": true
  }
}

// Set device tags for ACL-based access control
{
  "name": "tailscale_device_set_tags",
  "arguments": {
    "device_id": "device-id-here",
    "tags": ["tag:server", "tag:production"]
  }
}

Key Management

// Create a reusable, preauthorized key with tags
{
  "name": "tailscale_key_create",
  "arguments": {
    "reusable": true,
    "ephemeral": false,
    "preauthorized": true,
    "description": "CI/CD deployment key",
    "tags": ["tag:ci", "tag:automated"],
    "expiry_seconds": 86400
  }
}

// List all authentication keys
{
  "name": "tailscale_keys_list",
  "arguments": {}
}

DNS Configuration

// Set custom DNS nameservers
{
  "name": "tailscale_dns_nameservers_set",
  "arguments": {
    "nameservers": ["8.8.8.8", "8.8.4.4", "1.1.1.1"]
  }
}

// Enable MagicDNS for easy device connectivity
{
  "name": "tailscale_dns_preferences_set",
  "arguments": {
    "magic_dns": true
  }
}

// Set DNS search paths for short hostnames
{
  "name": "tailscale_dns_searchpaths_set",
  "arguments": {
    "search_paths": ["company.com", "internal.local"]
  }
}

Policy Management

// Get current ACL policy
{
  "name": "tailscale_policy_get",
  "arguments": {}
}

// Validate policy before applying
{
  "name": "tailscale_policy_validate",
  "arguments": {
    "policy": "{\n  \"acls\": [\n    {\n      \"action\": \"accept\",\n      \"src\": [\"tag:server\"],\n      \"dst\": [\"tag:database:5432\"]\n    }\n  ]\n}"
  }
}

// Update ACL policy
{
  "name": "tailscale_policy_set",
  "arguments": {
    "policy": "{\n  \"acls\": [\n    {\n      \"action\": \"accept\",\n      \"src\": [\"*\"],\n      \"dst\": [\"*:*\"]\n    }\n  ]\n}"
  }
}

Webhooks & Integrations

// Create webhook for device events
{
  "name": "tailscale_webhook_create",
  "arguments": {
    "endpoint_url": "https://your-app.com/webhook",
    "subscriptions": ["device.created", "device.deleted", "user.approved"]
  }
}

// Create device posture integration
{
  "name": "tailscale_device_posture_integration_create",
  "arguments": {
    "provider": "crowdstrike",
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "tenant_id": "your-tenant-id"
  }
}

🏗️ Architecture

The server follows a clean, modular architecture:

├── cmd/
│   └── main.go                 # Entry point and server setup
├── internal/
│   ├── config/                 # Configuration management
│   ├── client/                 # Tailscale client wrapper
│   └── handlers/               # MCP request handlers
├── pkg/
│   └── tools/                  # Tool implementations
│       ├── devices.go          # Device management (9 tools)
│       ├── keys.go             # Key management (4 tools)
│       ├── users.go            # User & contact management (8 tools)
│       ├── dns.go              # DNS & policy management (9 tools)
│       └── additional.go       # Advanced features (12 tools)
├── tailscale_api_docs/         # OpenAPI documentation
├── .gitignore                  # Git ignore rules
├── LICENSE.md                  # MIT License
└── README.md                   # This file

Key Design Principles

Modular: Each tool category is organized in separate files
Self-descriptive: Tools include comprehensive descriptions from OpenAPI docs
Type-safe: Full Go type safety with structured request/response handling
Error-resilient: Comprehensive error handling with informative messages
OAuth-ready: Support for both API key and OAuth authentication

🔐 Authentication & Security

OAuth Scopes

Each tool specifies the required OAuth scope in its description:

devices:read / devices:write - Device management
keys:read / keys:write - Authentication key management
users:read / users:write - User management
dns:read / dns:write - DNS configuration
acl:read / acl:write - ACL policy management
webhooks:read / webhooks:write - Webhook management
logging:read - Log configuration access
posture:read / posture:write - Device posture management
settings:read / settings:write - Tailnet settings

Security Best Practices

Store API keys and OAuth credentials securely
Use environment variables for sensitive configuration
Implement proper access controls in your MCP client
Regularly rotate API keys and OAuth credentials
Monitor API usage through Tailscale admin console

🛠️ Development

Adding New Tools

Identify the OpenAPI endpoint in tailscale_api_docs/tailscaleapi.yaml
Choose the appropriate file in pkg/tools/ based on functionality
Add the tool definition in the RegisterTools method:

tool := mcp.NewTool(
    "tailscale_new_tool",
    mcp.WithDescription("Detailed description with OAuth scope and use cases"),
    mcp.WithString("param", mcp.Description("Parameter description"), mcp.Required()),
)
mcpServer.AddTool(tool, dt.NewToolHandler)

Implement the handler function following existing patterns
Test thoroughly and update documentation

Enhanced Tool Descriptions

All tools include:

Detailed functionality description
OAuth scope requirements
Use cases and examples
Security considerations
Links to Tailscale documentation

Testing

# Run all tests
go test ./...

# Run tests with race detection
go test -race ./...

# Run tests with coverage
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Building for Different Platforms

Using Go Build

# Linux
GOOS=linux GOARCH=amd64 go build -o tailscale-mcp-server-linux ./cmd

# macOS
GOOS=darwin GOARCH=amd64 go build -o tailscale-mcp-server-macos ./cmd

# Windows
GOOS=windows GOARCH=amd64 go build -o tailscale-mcp-server.exe ./cmd

Using Docker Multi-Platform Build

# Build for multiple architectures
docker buildx create --use
docker buildx build --platform linux/amd64,linux/arm64 \
  -t tailscale-mcp-server:latest --push .

# Build for specific platform
docker build --platform linux/amd64 -t tailscale-mcp-server:amd64 .
docker build --platform linux/arm64 -t tailscale-mcp-server:arm64 .

📊 Monitoring & Observability

Built-in Logging

The server provides structured logging for:

Authentication attempts
API requests and responses
Error conditions
Performance metrics

Integration with Tailscale

Monitor API usage in the Tailscale admin console
Track OAuth token usage and refresh cycles
Review audit logs for security compliance

🐳 Docker Features

Security

Multi-stage build for minimal attack surface
Scratch base image (< 20MB final image)
Non-root user execution (UID 65534)
Read-only filesystem support
No new privileges security option
Dropped capabilities for enhanced security

Performance

Optimized binary with static linking
Resource limits (128MB RAM, 0.5 CPU by default)
Health checks for container monitoring
Graceful shutdown handling

Production Ready

Automatic restarts on failure
Structured logging to stdout/stderr
Environment-based configuration
Multi-architecture support (AMD64, ARM64)

Monitoring

# View real-time logs
docker logs -f tailscale-mcp-server

# Check health status
docker inspect --format='{{.State.Health.Status}}' tailscale-mcp-server

# Monitor resource usage
docker stats tailscale-mcp-server

🔗 Dependencies

tailscale.com/client/tailscale/v2 - Official Tailscale Go client library
github.com/mark3labs/mcp-go - MCP protocol implementation for Go
golang.org/x/oauth2 - OAuth 2.0 client library
Standard Go libraries - JSON, HTTP, context, logging

📄 License

This project is licensed under the MIT License. See LICENSE.md for details.

🤝 Contributing

Contributions are welcome! Please ensure all new tools include:

Complete input validation with proper error messages
Comprehensive error handling for all failure scenarios
Detailed descriptions following the OpenAPI documentation pattern
JSON response formatting consistent with existing tools
OAuth scope specifications in tool descriptions
Unit tests for core functionality
Documentation updates in this README

Development Workflow

Fork the repository
Create a feature branch: git checkout -b feature/new-tool
Implement your changes with tests
Run the test suite: go test ./...
Update documentation as needed
Submit a pull request with a clear description

📚 Resources

Tailscale API Documentation - Official API reference
MCP Protocol Specification - MCP protocol details
Tailscale Knowledge Base - Comprehensive guides and tutorials
Go Client Library Documentation - Official Go client docs

🆘 Support

Issues: Report bugs and request features on GitHub
Documentation: Refer to the Tailscale Knowledge Base
Community: Join the Tailscale community forums

Made with ❤️ for the Tailscale and MCP communities. This server provides the most comprehensive Tailscale MCP integration available, with self-descriptive tools powered by official OpenAPI documentation.

Name		Name	Last commit message	Last commit date
cmd		cmd
internal		internal
pkg/tools		pkg/tools
scripts		scripts
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE.md		LICENSE.md
README.md		README.md
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum

Latest commit

History

Folders and files

Repository files navigation