npm package: @hexsleeves/tailscale-mcp-server
Description: A 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.
Author: HexSleeves
Latest version: 0.3.2

# Tailscale MCP Server

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

<a href="https://glama.ai/mcp/servers/@HexSleeves/tailscale-mcp">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/@HexSleeves/tailscale-mcp/badge" alt="Tailscale Server MCP server" />
</a>

## 📦 Available Packages

- **NPM**: [`@hexsleeves/tailscale-mcp-server`](https://www.npmjs.com/package/@hexsleeves/tailscale-mcp-server)
- **Docker Hub**: [`hexsleeves/tailscale-mcp-server`](https://hub.docker.com/r/hexsleeves/tailscale-mcp-server)
- **GitHub Container Registry**: [`ghcr.io/hexsleeves/tailscale-mcp-server`](https://github.com/users/HexSleeves/packages/container/package/tailscale-mcp-server)

## 🚀 Recommended Package Manager

This project is optimized for **[Bun](https://bun.sh)** for faster installation and execution. NPM is supported as a fallback option.

### Quick Setup with Bun

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

### Fallback with NPM

```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](docs/workflows.md)** - GitHub Actions, testing pipelines, and release automation
- **[🧪 Testing Strategy](src/__test__/README.md)** - Unit tests, integration tests, and testing best practices
- **[🐳 Docker Guide](docs/docker.md)** - Container usage, development workflows, and deployment strategies

## Quick Start

### Option 1: NPX (Recommended)

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

### Option 2: Docker

```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](docs/docker.md)**

## Configuration

### Claude Desktop

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

### 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](https://login.tailscale.com/admin/settings/oauth)
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](https://tailscale.com/kb/1215/oauth-clients#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

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

### Development Commands

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

### Local Claude Desktop Configuration

```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](src/__test__/README.md)** - Unit tests, integration tests, coverage
> - **[Docker Development](docs/docker.md)** - Container-based development workflows
> - **[CI/CD Workflows](docs/workflows.md)** - GitHub Actions, automation, releases

### Project Structure

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

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

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

### 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](src/__test__/README.md))
- Follow the existing modular architecture
- Update documentation for new features

### Resources for Contributors

- **[Testing Strategy](src/__test__/README.md)** - How to write and run tests
- **[CI/CD Workflows](docs/workflows.md)** - Understanding the automation pipeline
- **[Docker Development](docs/docker.md)** - Container-based development workflows

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Support

- [Issues](https://github.com/your-repo/issues) - Bug reports and feature requests
- [Discussions](https://github.com/your-repo/discussions) - Questions and community support
- [MCP Documentation](https://modelcontextprotocol.io) - Learn more about MCP

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history and updates.