tailscale-mcp
server that provides seamless integration with Tailscale's CLI commands and REST API, enabling automated network management and monitoring through a standardized interface
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/HexSleeves/tailscale-mcp with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/HexSleeves/tailscale-mcp'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/hexsleeves--tailscale-mcp)HTML
<a href="/listings/hexsleeves--tailscale-mcp"><img src="/api/listings/hexsleeves--tailscale-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Claude Desktop
Edit `~/.claude/claude_desktop_config.json` (create if absent).
OAuth credentials (recommended)
{
"mcpServers": {
"tailscale": {
"command": "npx",
"args": ["-y", "@hexsleeves/tailscale-mcp-server"],
"env": {
"TAILSCALE_OAUTH_CLIENT_ID": "your-client-id",
"TAILSCALE_OAUTH_CLIENT_SECRET": "your-client-secret",
"TAILSCALE_TAILNET": "-"
}
}
}
}API key
{
"mcpServers": {
"tailscale": {
"command": "npx",
"args": ["-y", "@hexsleeves/tailscale-mcp-server"],
"env": {
"TAILSCALE_API_KEY": "tskey-api-...",
"TAILSCALE_TAILNET": "-"
}
}
}
}Enable write/admin tools
Add `TAILSCALE_ALLOWED_TOOL_RISK` to the `env` block:
"TAILSCALE_ALLOWED_TOOL_RISK": "write"
Set to `"admin"` to unlock destructive operations (delete, deauthorize, connect/disconnect, key mutation).
Docker Hub
{
"mcpServers": {
"tailscale": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "TAILSCALE_API_KEY=tskey-api-...",
"-e", "TAILSCALE_TAILNET=your-tailnet",
"hexsleeves/tailscale-mcp-server:latest"
]
}
}
}---
Claude Code (CLI)
claude mcp add tailscale \ -e TAILSCALE_API_KEY=tskey-api-... \ -e TAILSCALE_TAILNET=- \ -- npx -y @hexsleeves/tailscale-mcp-server
With write access:
claude mcp add tailscale \ -e TAILSCALE_API_KEY=tskey-api-... \ -e TAILSCALE_TAILNET=- \ -e TAILSCALE_ALLOWED_TOOL_RISK=write \ -- npx -y @hexsleeves/tailscale-mcp-server
---
Cursor
Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
{
"mcpServers": {
"tailscale": {
"command": "npx",
"args": ["-y", "@hexsleeves/tailscale-mcp-server"],
"env": {
"TAILSCALE_API_KEY": "tskey-api-...",
"TAILSCALE_TAILNET": "-"
}
}
}
}---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 391 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # Tailscale MCP Server
- <p align="center">
- <a href="https://www.npmjs.com/package/@hexsleeves/tailscale-mcp-server">
- <img src="https://img.shields.io/npm/v/@hexsleeves/tailscale-mcp-server?label=npm" alt="npm version" />
- </a>
- <a href="LICENSE">
- <img src="https://img.shields.io/github/license/HexSleeves/tailscale-mcp" alt="MIT License" />
- </a>
- <a href="https://github.com/HexSleeves/tailscale-mcp/actions/workflows/ci.yml">
- <img src="https://img.shields.io/github/actions/workflow/status/HexSleeves/tailscale-mcp/ci.yml?branch=main&label=CI" alt="CI status" />
- </a>
- <a href="https://hub.docker.com/r/hexsleeves/tailscale-mcp-server">
- <img src="https://img.shields.io/docker/v/hexsleeves/tailscale-mcp-server?label=Docker" alt="Docker image" />
- </a>
- </p>
- <p align="center">
- <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 MCP server on Glama" />
- </a>
- </p>
- A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for operating Tailscale from any MCP client. Supports local `stdio` for desktop clients and an authenticated HTTP transport for private tailnet deployments. Defaults to read-only access, localhost binding, and short-lived OAuth credentials where available.
- ---
- ## Table of Contents
- - [Features](#features)
- - [Requirements](#requirements)
- - [Quick Start](#quick-start)
- - [Claude Desktop](#claude-desktop)
- - [Claude Code (CLI)](#claude-code-cli)
- - [Cursor](#cursor)
- - [Tool Reference](#tool-reference)
- - [Resources and Prompts](#resources-and-prompts)
- - [Configuration](#configuration)
- - [HTTP Transport](#http-transport)
- - [Docker](#docker)
- - [Example Prompts](#example-prompts)
- - [Development](#development)
- - [Contributing](#contributing)
- ---
- ## Features
- - **Device management** — list, authorize, deauthorize, delete, expire keys, manage routes.
- - **Network operations** — connect/disconnect host, ping peers, get CLI status and version.
- - **Administration** — tailnet info, file sharing, exit nodes, webhooks, device tags, server version.
- - **ACL and policy** — read/validate/update ACL, DNS settings, auth keys, policy file, network lock.
- - **Read-only resources** — tailnet summary, device list, per-device detail, current ACL.
- - **Prompts** — guided connectivity diagnosis and ACL change review.
- - **Risk-gated tools** — `read`, `write`, and `admin` levels via `TAILSCALE_ALLOWED_TOOL_RISK`.
- - **OAuth + API key** — OAuth client credentials (preferred) or legacy API key.
- - **Private HTTP mode** — bearer auth, Host validation, request size limits, health check endpoint.
- - **Docker support** — pre-built images on Docker Hub and GHCR; sidecar deployment with Tailscale Serve.
- ---
- ## Requirements
- One of:
- - **Node.js 20+** — run via `npx` or install globally (no extra runtime needed).
- - **Bun 1.3+** — used for development; also works as a production runtime.
- - **Docker** — use the pre-built image (no local runtime required).
- Plus one auth method:
- - OAuth client credentials: `TAILSCALE_OAUTH_CLIENT_ID` + `TAILSCALE_OAUTH_CLIENT_SECRET` (preferred).
- - Legacy API key: `TAILSCALE_API_KEY`.
- The local **Tailscale CLI** is optional. It is only required for CLI-backed tools: `get_network_status`, `connect_network`, `disconnect_network`, `ping_peer`, `get_version`, and `manage_exit_nodes` (set/clear operations).
- ---
- ## Quick Start
- ### Claude Desktop
- Edit `~/.claude/claude_desktop_config.json` (create if absent).
- #### OAuth credentials (recommended)
- ```json
- {
- "mcpServers": {
- "tailscale": {
- "command": "npx",
- "args": ["-y", "@hexsleeves/tailscale-mcp-server"],
- "env": {
- "TAILSCALE_OAUTH_CLIENT_ID": "your-client-id",
- "TAILSCALE_OAUTH_CLIENT_SECRET": "your-client-secret",
- "TAILSCALE_TAILNET": "-"
- }
- }
- }
- }
- ```
- #### API key
- ```json
- {
- "mcpServers": {
- "tailscale": {
- "command": "npx",
- "args": ["-y", "@hexsleeves/tailscale-mcp-server"],
- "env": {
- "TAILSCALE_API_KEY": "tskey-api-...",
- "TAILSCALE_TAILNET": "-"
- }
- }
- }
- }
- ```
- #### Enable write/admin tools
- Add `TAILSCALE_ALLOWED_TOOL_RISK` to the `env` block:
- ```json
- "TAILSCALE_ALLOWED_TOOL_RISK": "write"
- ```
- Set to `"admin"` to unlock destructive operations (delete, deauthorize, connect/disconnect, key mutation).
- #### Docker Hub
- ```json
- {
- "mcpServers": {
- "tailscale": {
- "command": "docker",
- "args": [
- "run", "--rm", "-i",
- "-e", "TAILSCALE_API_KEY=tskey-api-...",
- "-e", "TAILSCALE_TAILNET=your-tailnet",
- "hexsleeves/tailscale-mcp-server:latest"
- ]
- }
- }
- }
- ```
- ---
- ### Claude Code (CLI)
- ```bash
- claude mcp add tailscale \
- -e TAILSCALE_API_KEY=tskey-api-... \
- -e TAILSCALE_TAILNET=- \
- -- npx -y @hexsleeves/tailscale-mcp-server
- ```
- With write access:
- ```bash
- claude mcp add tailscale \
- -e TAILSCALE_API_KEY=tskey-api-... \
- -e TAILSCALE_TAILNET=- \
- -e TAILSCALE_ALLOWED_TOOL_RISK=write \
- -- npx -y @hexsleeves/tailscale-mcp-server
- ```
- ---
- ### Cursor
- Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
- ```json
- {
- "mcpServers": {
- "tailscale": {
- "command": "npx",
- "args": ["-y", "@hexsleeves/tailscale-mcp-server"],
- "env": {
- "TAILSCALE_API_KEY": "tskey-api-...",
- "TAILSCALE_TAILNET": "-"
- }
- }
- }
- }
- ```
- ---
- ## Tool Reference
- ### Devices
- | Tool | Description | Min risk |
- |------|-------------|----------|
- | `list_devices` | List all devices in the configured tailnet | `read` |
- | `device_action` | Authorize or expire a device key (`write`); deauthorize or delete (`admin`) | `write` / `admin` |
- | `manage_routes` | Enable or disable advertised routes for a device | `write` |
- ### Network
- | Tool | Description | Min risk |
- |------|-------------|----------|
- | `get_network_status` | Get current Tailscale network status via local CLI | `read` |
- | `connect_network` | Connect this host to Tailscale with optional CLI flags | `admin` |
- | `disconnect_network` | Disconnect this host from Tailscale | `admin` |
- | `ping_peer` | Ping a Tailscale peer through the local CLI | `read` |
- | `get_version` | Get local Tailscale CLI version information | `read` |
- ### Administration
- | Tool | Description | Min risk |
- |------|-------------|----------|
- | `get_tailnet_info` | Get detailed information about the configured tailnet | `read` |
- | `manage_file_sharing` | Read (`read`) or update (`write`) tailnet file sharing settings | `read` / `write` |
- | `manage_exit_nodes` | List exit nodes (`read`); set, clear, advertise, or stop advertising (`admin`) | `read` / `admin` |
- | `manage_webhooks` | List webhooks (`read`); create, delete, or test webhooks (`write`) | `read` / `write` |
- | `manage_device_tags` | Read (`read`) or update (`write`) tags for a device | `read` / `write` |
- | `get_version_info` | Return server version identifier | `read` |
- ### ACL and Policy
- | Tool | Description | Min risk |
- |------|-------------|----------|
- | `manage_acl` | Read (`read`), validate, or update (`write`) the tailnet ACL policy | `read` / `write` |
- | `manage_dns` | Read (`read`) or update (`write`) Tailscale DNS settings | `read` / `write` |
- | `manage_keys` | List auth keys (`read`); create or delete (`admin`) | `read` / `admin` |
- | `manage_policy_file` | Read (`read`) or update (`write`) the tailnet policy file | `read` / `write` |
- | `manage_network_lock` | Network lock status (`read`) and mutation operations (`admin`) | `read` / `admin` |
- ---
- ## Resources and Prompts
- ### Resources (read-only)
- | URI | Description |
- |-----|-------------|
- | `tailscale://tailnet/summary` | High-level tailnet summary |
- | `tailscale://devices` | All devices in the tailnet |
- | `tailscale://devices/{deviceId}` | Detail for a single device |
- | `tailscale://acl/current` | Current ACL policy |
- ### Prompts
- | Name | Description |
- |------|-------------|
- | `diagnose_tailnet_connectivity` | Guided diagnostic for connectivity issues |
- | `review_acl_change` | Structured review workflow for ACL policy changes |
- ---
- ## Configuration
- | Variable | Default | Description |
- |----------|---------|-------------|
- | `TAILSCALE_OAUTH_CLIENT_ID` | — | OAuth client ID (preferred auth method) |
- | `TAILSCALE_OAUTH_CLIENT_SECRET` | — | OAuth client secret (required with `CLIENT_ID`) |
- | `TAILSCALE_API_KEY` | — | Legacy API key fallback |
- | `TAILSCALE_TAILNET` | `-` | Tailnet name or `-` shorthand for the default tailnet |
- | `TAILSCALE_API_BASE_URL` | `https://api.tailscale.com` | Tailscale API base URL (https required except for localhost) |
- | `TAILSCALE_ALLOWED_TOOL_RISK` | `read` | Maximum allowed tool risk: `read`, `write`, or `admin` |
- | `TAILSCALE_CLI_PATH` | `tailscale` | Path to the local Tailscale CLI binary |
- | `MCP_TRANSPORT` | `stdio` | Transport mode: `stdio` or `http` |
- | `MCP_HTTP_BIND_HOST` | `127.0.0.1` | Host to bind in HTTP mode |
- | `MCP_HTTP_PORT` | `3000` | Port to bind in HTTP mode |
- | `MCP_HTTP_BEARER_TOKEN` | — | Required for HTTP mode (minimum 32 characters) |
- | `MCP_ALLOWED_HOSTS` | — | Comma-separated additional allowed HTTP Host header values |
- | `LOG_LEVEL` | `info` | Log verbosity: `debug`, `info`, `warn`, or `error` |
- | `MCP_SERVER_LOG_FILE` | — | Optional file path for log output |
- ### Risk levels
- - `read` — list devices, inspect status, read resources, run diagnostics.
- - `write` — update ACLs, DNS, routes, policy files, webhooks, tags, and other mutating settings.
- - `admin` — destructive or host-affecting operations: delete, deauthorize, connect, disconnect, auth key mutation, file sharing changes, exit node control.
- ---
- ## HTTP Transport
- HTTP mode is intended for private tailnet access. It requires `MCP_HTTP_BEARER_TOKEN` and binds to `127.0.0.1` by default.
- ```bash
- export MCP_TRANSPORT=http
- export MCP_HTTP_BEARER_TOKEN="$(openssl rand -base64 32)"
- export TAILSCALE_OAUTH_CLIENT_ID="your-client-id"
- export TAILSCALE_OAUTH_CLIENT_SECRET="your-client-secret"
- export TAILSCALE_TAILNET="-"
- npx -y @hexsleeves/tailscale-mcp-server --http --host 127.0.0.1 --port 3000
- ```
- Expose privately with Tailscale Serve (recommended for tailnet deployments):
- ```bash
- tailscale serve --bg 443 localhost:3000
- ```
- Do not use Tailscale Funnel for normal MCP operation. Funnel makes the endpoint publicly reachable on the internet.
- A `GET /health` endpoint returns `200 OK` when the server is running.
- For full Docker sidecar deployment instructions, see [docs/docker.md](docs/docker.md).
- ---
- ## Docker
- ### Run with Docker Hub image
- ```bash
- docker run --rm \
- -e TAILSCALE_API_KEY="tskey-api-..." \
- -e TAILSCALE_TAILNET="-" \
- -p 127.0.0.1:3000:3000 \
- hexsleeves/tailscale-mcp-server:latest
- ```
- ### Run with GHCR image
- ```bash
- docker run --rm \
- -e TAILSCALE_API_KEY="tskey-api-..." \
- -e TAILSCALE_TAILNET="-" \
- -p 127.0.0.1:3000:3000 \
- ghcr.io/hexsleeves/tailscale-mcp-server:latest
- ```
- ### Build locally
- ```bash
- docker build -t tailscale-mcp-server .
- ```
- For sidecar deployment with Tailscale Serve, see [docs/docker.md](docs/docker.md).
- ---
- ## Example Prompts
- Once the server is connected to your MCP client, try these:
- - "List my Tailscale devices and show which ones are offline."
- - "What is the current Tailscale network status on this machine?"
- - "Diagnose connectivity to my NAS at 100.64.0.5."
- - "Show me the current ACL policy for my tailnet."
- - "Review this ACL change before I apply it." *(attach the new policy)*
- - "What DNS nameservers is my tailnet using?"
- - "List all active webhooks in my tailnet."
- ---
- ## Development
- ```bash
- # Install dependencies (Bun required for development)
- bun install
- # Type check
- bun run typecheck
- # Run tests
- bun test
- # Lint and format
- bun run check
- # Build
- bun run build
- # Full verification (typecheck + lint + test + build)
- bun run qa:full
- # Security audit
- bun audit
- ```
- See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development workflow, commit conventions, and release process.
- ---
- ## Contributing
- Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
- - [CONTRIBUTING.md](CONTRIBUTING.md) — development setup, commit conventions, PR process.
- - [SECURITY.md](SECURITY.md) — responsible disclosure policy.
- - [LICENSE](LICENSE) — MIT.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.