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

Related MCP server: ConnectWise API Gateway 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

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)

General Configuration

*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

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.