Tailscale MCP Server

A modern Model Context Protocol (MCP) server that provides seamless integration with Tailscale's CLI commands and REST API, enabling automated network management and monitoring through a standardized interface.

📦 Available Packages

• NPM: @hexsleeves/tailscale-mcp-server
• Docker Hub: hexsleeves/tailscale-mcp-server
• GitHub Container Registry: ghcr.io/hexsleeves/tailscale-mcp-server

🚀 Recommended Package Manager

This project is optimized for Bun for faster installation and execution. NPM is supported as a fallback option.

Quick Setup with Bun

# Install Bun (if not already installed)
curl -fsSL https://bun.sh/install | bash

# Install dependencies
bun install

# Build and run
bun run build
bun start

Fallback with NPM

npm ci
npm run build
npm start

Features

• Device Management: List, authorize, deauthorize, and manage Tailscale devices
• Network Operations: Connect/disconnect, manage routes, and monitor network status
• Security Controls: Manage ACLs, device tags, and network lock settings
• Modern Architecture: Modular tool system with TypeScript and Zod validation
• CLI Integration: Direct integration with Tailscale CLI commands
• API Integration: REST API support for advanced operations

📚 Documentation

This project includes comprehensive documentation organized by domain:

• 🔧 CI/CD Workflows - GitHub Actions, testing pipelines, and release automation
• 🧪 Testing Strategy - Unit tests, integration tests, and testing best practices
• 🐳 Docker Guide - Container usage, development workflows, and deployment strategies

Quick Start

Option 1: NPX (Recommended)

Run directly without installation:

# Explicit package syntax (most reliable)
npx --package=@hexsleeves/tailscale-mcp-server tailscale-mcp-server

# Or install globally
npm install -g @hexsleeves/tailscale-mcp-server
tailscale-mcp-server

Option 2: Docker

# GitHub Container Registry (recommended)
docker run -d \
  --name tailscale-mcp \
  -e TAILSCALE_API_KEY=your_api_key \
  -e TAILSCALE_TAILNET=your_tailnet \
  ghcr.io/hexsleeves/tailscale-mcp-server:latest

# Or use Docker Compose
docker-compose up -d

📖 For detailed Docker usage, development workflows, and deployment strategies, see the Docker Guide

Configuration

Claude Desktop

Add to your Claude Desktop configuration (~/.claude/claude_desktop_config.json):

Using NPX (Recommended)

{
  "mcpServers": {
    "tailscale": {
      "command": "npx",
      "args": [
        "--package=@hexsleeves/tailscale-mcp-server",
        "tailscale-mcp-server"
      ],
      "env": {
        "TAILSCALE_API_KEY": "your-api-key-here",
        "TAILSCALE_TAILNET": "your-tailnet-name"
      }
    }
  }
}

Using Docker

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

Environment Variables

Authentication (choose one method)

Variable	Description	Required
TAILSCALE_API_KEY	Tailscale API key	Option 1
TAILSCALE_OAUTH_CLIENT_ID	OAuth client ID	Option 2
TAILSCALE_OAUTH_CLIENT_SECRET	OAuth client secret	Option 2

General Configuration

Variable	Description	Required	Default
TAILSCALE_TAILNET	Tailscale tailnet name	Yes*	-
TAILSCALE_API_BASE_URL	API base URL	No	https://api.tailscale.com
LOG_LEVEL	Logging level (0-3)	No	1 (INFO)
MCP_SERVER_LOG_FILE	Server log file path	No	-

*Required for API-based operations. CLI operations work without API credentials.

OAuth vs API Key Authentication

API Key (TAILSCALE_API_KEY):

• Full permissions matching the user who created the key
• Expires in 1-90 days
• Tied to a specific user account

OAuth Client (TAILSCALE_OAUTH_CLIENT_ID + TAILSCALE_OAUTH_CLIENT_SECRET):

• Scoped permissions (e.g., read-only device access)
• Does not expire (but can be revoked)
• Not tied to any user account
• Recommended for automation and least-privilege access

Creating an OAuth Client

1. Go to Tailscale OAuth Settings
2. Click "Generate OAuth client"
3. Select the required scopes (e.g., devices:read for read-only device access)
4. Copy the client ID and secret

OAuth Configuration Example

{
  "mcpServers": {
    "tailscale": {
      "command": "npx",
      "args": [
        "--package=@hexsleeves/tailscale-mcp-server",
        "tailscale-mcp-server"
      ],
      "env": {
        "TAILSCALE_OAUTH_CLIENT_ID": "your-oauth-client-id",
        "TAILSCALE_OAUTH_CLIENT_SECRET": "your-oauth-client-secret",
        "TAILSCALE_TAILNET": "your-tailnet-name"
      }
    }
  }
}

Available OAuth Scopes

Scope	Description
all:read	Read-only access to all resources
devices:read	Read device information
devices:core	Full device management
dns:read	Read DNS settings
dns:write	Modify DNS settings
acl:read	Read ACL configuration
acl:write	Modify ACL configuration
auth_keys	Manage authentication keys

See Tailscale OAuth Scopes for a complete list.

Available Tools

Device Management

• list_devices - List all devices in the Tailscale network
• device_action - Perform actions on specific devices (authorize, deauthorize, delete, expire-key)
• manage_routes - Enable or disable routes for devices

Network Operations

• get_network_status - Get current network status from Tailscale CLI
• connect_network - Connect to the Tailscale network
• disconnect_network - Disconnect from the Tailscale network
• ping_peer - Ping a peer device

System Information

• get_version - Get Tailscale version information
• get_tailnet_info - Get detailed network information

Development

Quick Setup

# Clone and setup
git clone https://github.com/HexSleeves/tailscale-mcp-server.git
cd tailscale-mcp-server

# Install Bun (recommended) or use npm
curl -fsSL https://bun.sh/install | bash
bun install  # or: npm install

# Setup environment
cp .env.example .env
# Edit .env with your Tailscale credentials

# Build and run
bun run build  # or: npm run build
bun start      # or: npm start

Development Commands

# Development workflow (Bun recommended)
bun run dev:direct        # Fast development with tsx
bun run dev:watch         # Auto-rebuild on changes
bun run build:watch       # Build with file watching

# Development workflow (NPM fallback)
npm run dev:direct
npm run dev:watch
npm run build:watch

# Testing (Bun recommended)
bun test                  # All tests
bun run test:unit         # Unit tests only
bun run test:integration  # Integration tests (requires Tailscale CLI)
bun run test:watch        # Watch mode

# Testing (NPM fallback)
npm test
npm run test:unit
npm run test:integration
npm run test:watch

# Quality assurance (Bun recommended)
bun run qa                # Quick QA (typecheck + unit tests + lint)
bun run qa:full           # Full QA (all tests + checks)
bun run typecheck         # TypeScript validation

# Quality assurance (NPM fallback)
npm run qa
npm run qa:full
npm run typecheck

# Tools (Bun recommended)
bun run inspector         # Test with MCP Inspector

# Tools (NPM fallback)
npm run inspector

Local Claude Desktop Configuration

{
  "mcpServers": {
    "tailscale-dev": {
      "command": "node",
      "args": ["/path/to/your/tailscale-mcp-server/dist/index.js"],
      "env": {
        "TAILSCALE_API_KEY": "your-api-key-here",
        "TAILSCALE_TAILNET": "your-tailnet-name",
        "LOG_LEVEL": "0"
      }
    }
  }
}

📖 For comprehensive development guides, testing strategies, and CI/CD information:

• Testing Documentation - Unit tests, integration tests, coverage
• Docker Development - Container-based development workflows
• CI/CD Workflows - GitHub Actions, automation, releases

Project Structure

src/
├── server.ts              # Main server implementation
├── tools/                 # Modular tool definitions
├── tailscale/             # Tailscale integrations
├── types.ts               # Type definitions
├── logger.ts              # Logging utilities
└── index.ts               # Entry point

Adding New Tools

Create a tool module in src/tools/ and register it in src/server.ts. See existing tools for examples of the modular architecture using Zod schemas and TypeScript.

Debugging

# Enable debug logging
export LOG_LEVEL=0
export MCP_SERVER_LOG_FILE=debug-{timestamp}.log

# View logs
tail -f logs/debug-*.log

API Reference

Tool Categories

Device Tools

• Device listing and filtering
• Device authorization management
• Route management per device

Network Tools

• Network status monitoring
• Connection management
• Peer connectivity testing

Security Tools

• ACL management
• Device tagging
• Network lock operations

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Run quality checks: bun run qa:full (or npm run qa:full)
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

Development Guidelines

• Use TypeScript for all new code
• Add Zod schemas for input validation
• Include tests for new tools (see Testing Guide)
• Follow the existing modular architecture
• Update documentation for new features

Resources for Contributors

• Testing Strategy - How to write and run tests
• CI/CD Workflows - Understanding the automation pipeline
• Docker Development - Container-based development workflows

License

MIT License - see LICENSE file for details.

Support

• Issues - Bug reports and feature requests
• Discussions - Questions and community support
• MCP Documentation - Learn more about MCP

Changelog

See CHANGELOG.md for version history and updates.