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.

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

Quick Start

Installation

# Install globally
npm install -g @hexsleeve/tailscale-mcp-server

# Or run directly
npx @hexsleeve/tailscale-mcp-server

Development Setup

# Clone the repository
git clone <repository-url>
cd TailscaleMcp

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

Configuration

Claude Desktop

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

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

Environment Variables

# Required for API operations
export TAILSCALE_API_KEY="your-api-key"
export TAILSCALE_TAILNET="your-tailnet"

# Optional: Custom API base URL
export TAILSCALE_API_BASE_URL="https://api.tailscale.com"

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

Project Structure

src/
├── server.ts              # Main server implementation
├── tools/                 # Modular tool definitions
│   ├── index.ts           # Tool registry system
│   ├── device-tools.ts    # Device management tools
│   └── ...                # Additional tool modules
├── tailscale/             # Tailscale integrations
│   ├── tailscale-api.ts   # REST API client
│   ├── tailscale-cli.ts   # CLI wrapper
│   └── index.ts           # Exports
├── types.ts               # Type definitions
├── logger.ts              # Logging utilities
└── index.ts               # Entry point

Adding New Tools

Create a new tool module in src/tools/:

import { z } from "zod";
import type { ToolModule, ToolContext } from "./index.js";

const MyToolSchema = z.object({
  param: z.string().describe("Description of parameter"),
});

async function myTool(
  args: z.infer<typeof MyToolSchema>,
  context: ToolContext
) {
  // Implementation
  return {
    content: [{ type: "text", text: "Result" }],
  };
}

export const myTools: ToolModule = {
  tools: [
    {
      name: "my_tool",
      description: "Description of what this tool does",
      inputSchema: MyToolSchema,
      handler: myTool,
    },
  ],
};

import { myTools } from "./tools/my-tools.js";

// In the constructor:
this.toolRegistry.registerModule(myTools);

Testing

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Test with MCP Inspector
npm run inspector

Building

# Build for production
npm run build

# Build for development
npm run build:dev

# Build and watch for changes
npm run build:watch

API Reference

Environment Variables

Variable	Description	Required	Default
`TAILSCALE_API_KEY`	Tailscale API key	Yes*	-
`TAILSCALE_TAILNET`	Tailscale tailnet name	Yes*	-
`TAILSCALE_API_BASE_URL`	API base URL	No	`https://api.tailscale.com`

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

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

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes
Add tests for new functionality
Ensure all tests pass: npm test
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Development Guidelines

Use TypeScript for all new code
Add Zod schemas for input validation
Include tests for new tools
Follow the existing modular architecture
Update documentation for new features

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.

This server cannot be installed

security - not tested

license - not found

quality - not tested

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Provides seamless integration with Tailscale's CLI commands and REST API, enabling automated network management and monitoring through a standardized Model Context Protocol interface.

Related MCP Servers

Linear MCP Server
tiovikram
A
security
F
license
A
quality
Enables interaction with Linear's API for managing issues, teams, and projects programmatically through the Model Context Protocol.
Last updated -
7
83
1
JavaScript
MCP Server for Spinnaker
dion-hagan
-
security
A
license
-
quality
A Model Context Protocol server implementation that allows AI models to interact with and manage Spinnaker deployments, pipelines, and applications through a standardized interface.
Last updated -
14
TypeScript
MIT License
Sentry MCP Server
codyde
A
security
F
license
A
quality
A Model Context Protocol server that enables AI assistants to interact with Sentry for error tracking and monitoring, allowing retrieval and analysis of error data, project management, and performance monitoring through the Sentry API.
Last updated -
10
3
TypeScript
AWS CodePipeline MCP Server
cuongdev
-
security
F
license
-
quality
A Model Context Protocol server that integrates with AWS CodePipeline, allowing users to manage pipelines through Windsurf and Cascade using natural language commands.
Last updated -
4
TypeScript

View all related MCP servers

Tailscale MCP Server