A
security-
licenseA
qualityA Model Context Protocol server that integrates with AWS CodePipeline, allowing users to manage pipelines through Windsurf and Cascade using natural language commands.
Last updated -
12
4
The Tailscale MCP Server provides a standardized interface for automating Tailscale network management through CLI and REST API integration. With this server, you can:
Device Management: List, authorize, deauthorize, and delete devices; manage routes and tags
Network Operations: Connect/disconnect networks, check status, and ping peers
Security Controls: Manage ACLs, policy files, device tags, and network lock settings
DNS Management: Configure nameservers, search paths, and MagicDNS preferences
Key Management: Create, list, and delete authentication keys with specific capabilities
Additional Features: Configure exit nodes, manage file sharing, set up webhooks, and retrieve version information
Built on Node.js runtime (requires v18+) with ES module support for executing Tailscale CLI commands and interacting with the Tailscale REST API.
Provides tools for managing Tailscale networks, including device management (listing, authorizing/deauthorizing devices), subnet route control, network connectivity operations (connect/disconnect), and peer monitoring via ping functionality.
Leverages TypeScript for type safety throughout the implementation, with Zod validation for schema validation and type checking of inputs and outputs.
Uses Zod for runtime validation of data schemas, ensuring type safety and providing descriptive error messages for invalid parameters.
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
Docker Hub:
hexsleeves/tailscale-mcp-serverGitHub 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
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
Variable | Description | Required | Default |
| Tailscale API key | Yes* | - |
| Tailscale tailnet name | Yes* | - |
| API base URL | No |
|
| Logging level (0-3) | No |
(INFO) |
| Server log file path | No | - |
*Required for API-based operations. CLI operations work without API credentials.
Available Tools
Device Management
list_devices- List all devices in the Tailscale networkdevice_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 CLIconnect_network- Connect to the Tailscale networkdisconnect_network- Disconnect from the Tailscale networkping_peer- Ping a peer device
System Information
get_version- Get Tailscale version informationget_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
Fork the repository
Create a feature branch:
git checkout -b feature/amazing-featureMake your changes and add tests
Run quality checks:
bun run qa:full(ornpm run qa:full)Commit your changes:
git commit -m 'Add amazing feature'Push to the branch:
git push origin feature/amazing-featureOpen 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.
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
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
- -security-license-qualityA Model Context Protocol server that provides a comprehensive interface for interacting with the ConnectWise Manage API, simplifying API discovery, execution, and management for both developers and AI assistants.Last updated -06
- Asecurity-licenseAqualityA Model Context Protocol server that provides network packet capture and analysis capabilities through Wireshark/tshark integration, enabling AI assistants to perform network security analysis and troubleshooting.Last updated -423MIT License
- -security-license-qualityAn 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.Last updated -2MIT License