Tailscale

You can run and manage the Tailscale MCP Server to automate network management with a consistent interface. It integrates with Tailscale CLI commands and REST APIs, letting you list devices, manage routes, enforce security policies, monitor network status, and run common MCP workflows from a single server.

How to use

You operate the MCP server through an MCP client that speaks the defined tool set. The server exposes device, network, and system operations that you can invoke to manage your Tailscale tailnet. Typical usage patterns include listing devices, authorizing or deauthorizing devices, enabling routes for devices, checking network status, connecting or disconnecting from Tailscale, and querying version or tailnet information. You can also integrate with a REST API for advanced automation or use the CLI wrapper to drive actions from scripts.

To start quickly, you can run the server via NPX or from a Docker image. Use environment variables to supply your Tailscale API key and tailnet, and adjust logging as needed.

How to install

Prerequisites you need before starting: node/npm or Docker, depending on how you want to run the MCP server.

Option A: NPX (recommended for quick trials) — run directly without a local install.

# Method 1: Explicit package syntax (most reliable)
npx --package=@hexsleeves/tailscale-mcp-server tailscale-mcp-server

# Method 2: Direct syntax (may work depending on npx version)
npx -y @hexsleeves/tailscale-mcp-server

If you prefer to install locally, you can install the package globally and start the server with the standard command.

npm install -g @hexsleeves/tailscale-mcp-server
tailscale-mcp-server

Configuration and runtime notes

The server expects credentials and target information to operate against the Tailscale API. You supply these via environment variables and, if needed, a base API URL for custom endpoints.

This server supports various ways to run, including directly with NPX or via Docker. You can pass credentials through environment Variables.

Additional setup and examples

Using Docker Hub or GHCR images lets you run the MCP server in containers with a single command. The following examples show how to launch with required environment variables.

# Docker Hub
docker run -d \
  --name tailscale-mcp \
  -e TAILSCALE_API_KEY=your_api_key \
  -e TAILSCALE_TAILNET=your_tailnet \
  hexsleeves/tailscale-mcp-server:latest

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

Environment variables

Configure credentials and optional settings to control API access, logging, and base URL.

Required for API operations: set the API key and tailnet.

Optional: customize the API base URL and logging behavior.

Troubleshooting and tips

If you encounter connection issues, verify that your TAILSCALE_API_KEY and TAILSCALE_TAILNET are correct and that the server can reach the tailscale API. Check logs for the configured log level and ensure the MCP server has network access.

Available tools

list_devices

List all devices in your Tailscale tailnet.

device_action

Authorize, deauthorize, delete, or expire a device key.

manage_routes

Enable or disable network routes for specific devices.

get_network_status

Fetch current network status from the Tailscale CLI.

connect_network

Connect to the Tailscale network.

disconnect_network

Disconnect from the Tailscale network.

ping_peer

Ping a peer device to check connectivity.

get_version

Retrieve the Tailscale version information.

get_tailnet_info

Get detailed information about your tailnet.