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.

$3

``bash


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
`

$3

`bash
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

$3

Run directly without installation:

`bash


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
`

$3

`bash


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

$3

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

#### Using NPX (Recommended)

`json
{
"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

`json
{
"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"
]
}
}
}
`

$3

#### 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.

$3

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

`json
{
"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

$3

- 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

$3

- 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

$3

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

Development

$3

`bash


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
`

$3

`bash


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
`

$3

`json
{
"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

$3

`bash
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
`

$3

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.

$3

`bash


Enable debug logging

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

View logs

tail -f logs/debug-*.log
`

API Reference

$3

#### 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

$3

- 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

$3

- 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.