Skip to content
Back to search

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hexsleeves--tailscale-mcp/badge.svg)](/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

i

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)

  1. # Tailscale MCP Server
  2. <p align="center">
  3. <a href="https://www.npmjs.com/package/@hexsleeves/tailscale-mcp-server">
  4. <img src="https://img.shields.io/npm/v/@hexsleeves/tailscale-mcp-server?label=npm" alt="npm version" />
  5. </a>
  6. <a href="LICENSE">
  7. <img src="https://img.shields.io/github/license/HexSleeves/tailscale-mcp" alt="MIT License" />
  8. </a>
  9. <a href="https://github.com/HexSleeves/tailscale-mcp/actions/workflows/ci.yml">
  10. <img src="https://img.shields.io/github/actions/workflow/status/HexSleeves/tailscale-mcp/ci.yml?branch=main&label=CI" alt="CI status" />
  11. </a>
  12. <a href="https://hub.docker.com/r/hexsleeves/tailscale-mcp-server">
  13. <img src="https://img.shields.io/docker/v/hexsleeves/tailscale-mcp-server?label=Docker" alt="Docker image" />
  14. </a>
  15. </p>
  16. <p align="center">
  17. <a href="https://glama.ai/mcp/servers/@HexSleeves/tailscale-mcp">
  18. <img width="380" height="200" src="https://glama.ai/mcp/servers/@HexSleeves/tailscale-mcp/badge" alt="Tailscale MCP server on Glama" />
  19. </a>
  20. </p>
  21. 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.
  22. ---
  23. ## Table of Contents
  24. - [Features](#features)
  25. - [Requirements](#requirements)
  26. - [Quick Start](#quick-start)
  27. - [Claude Desktop](#claude-desktop)
  28. - [Claude Code (CLI)](#claude-code-cli)
  29. - [Cursor](#cursor)
  30. - [Tool Reference](#tool-reference)
  31. - [Resources and Prompts](#resources-and-prompts)
  32. - [Configuration](#configuration)
  33. - [HTTP Transport](#http-transport)
  34. - [Docker](#docker)
  35. - [Example Prompts](#example-prompts)
  36. - [Development](#development)
  37. - [Contributing](#contributing)
  38. ---
  39. ## Features
  40. - **Device management** — list, authorize, deauthorize, delete, expire keys, manage routes.
  41. - **Network operations** — connect/disconnect host, ping peers, get CLI status and version.
  42. - **Administration** — tailnet info, file sharing, exit nodes, webhooks, device tags, server version.
  43. - **ACL and policy** — read/validate/update ACL, DNS settings, auth keys, policy file, network lock.
  44. - **Read-only resources** — tailnet summary, device list, per-device detail, current ACL.
  45. - **Prompts** — guided connectivity diagnosis and ACL change review.
  46. - **Risk-gated tools** — `read`, `write`, and `admin` levels via `TAILSCALE_ALLOWED_TOOL_RISK`.
  47. - **OAuth + API key** — OAuth client credentials (preferred) or legacy API key.
  48. - **Private HTTP mode** — bearer auth, Host validation, request size limits, health check endpoint.
  49. - **Docker support** — pre-built images on Docker Hub and GHCR; sidecar deployment with Tailscale Serve.
  50. ---
  51. ## Requirements
  52. One of:
  53. - **Node.js 20+** — run via `npx` or install globally (no extra runtime needed).
  54. - **Bun 1.3+** — used for development; also works as a production runtime.
  55. - **Docker** — use the pre-built image (no local runtime required).
  56. Plus one auth method:
  57. - OAuth client credentials: `TAILSCALE_OAUTH_CLIENT_ID` + `TAILSCALE_OAUTH_CLIENT_SECRET` (preferred).
  58. - Legacy API key: `TAILSCALE_API_KEY`.
  59. 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).
  60. ---
  61. ## Quick Start
  62. ### Claude Desktop
  63. Edit `~/.claude/claude_desktop_config.json` (create if absent).
  64. #### OAuth credentials (recommended)
  65. ```json
  66. {
  67. "mcpServers": {
  68. "tailscale": {
  69. "command": "npx",
  70. "args": ["-y", "@hexsleeves/tailscale-mcp-server"],
  71. "env": {
  72. "TAILSCALE_OAUTH_CLIENT_ID": "your-client-id",
  73. "TAILSCALE_OAUTH_CLIENT_SECRET": "your-client-secret",
  74. "TAILSCALE_TAILNET": "-"
  75. }
  76. }
  77. }
  78. }
  79. ```
  80. #### API key
  81. ```json
  82. {
  83. "mcpServers": {
  84. "tailscale": {
  85. "command": "npx",
  86. "args": ["-y", "@hexsleeves/tailscale-mcp-server"],
  87. "env": {
  88. "TAILSCALE_API_KEY": "tskey-api-...",
  89. "TAILSCALE_TAILNET": "-"
  90. }
  91. }
  92. }
  93. }
  94. ```
  95. #### Enable write/admin tools
  96. Add `TAILSCALE_ALLOWED_TOOL_RISK` to the `env` block:
  97. ```json
  98. "TAILSCALE_ALLOWED_TOOL_RISK": "write"
  99. ```
  100. Set to `"admin"` to unlock destructive operations (delete, deauthorize, connect/disconnect, key mutation).
  101. #### Docker Hub
  102. ```json
  103. {
  104. "mcpServers": {
  105. "tailscale": {
  106. "command": "docker",
  107. "args": [
  108. "run", "--rm", "-i",
  109. "-e", "TAILSCALE_API_KEY=tskey-api-...",
  110. "-e", "TAILSCALE_TAILNET=your-tailnet",
  111. "hexsleeves/tailscale-mcp-server:latest"
  112. ]
  113. }
  114. }
  115. }
  116. ```
  117. ---
  118. ### Claude Code (CLI)
  119. ```bash
  120. claude mcp add tailscale \
  121. -e TAILSCALE_API_KEY=tskey-api-... \
  122. -e TAILSCALE_TAILNET=- \
  123. -- npx -y @hexsleeves/tailscale-mcp-server
  124. ```
  125. With write access:
  126. ```bash
  127. claude mcp add tailscale \
  128. -e TAILSCALE_API_KEY=tskey-api-... \
  129. -e TAILSCALE_TAILNET=- \
  130. -e TAILSCALE_ALLOWED_TOOL_RISK=write \
  131. -- npx -y @hexsleeves/tailscale-mcp-server
  132. ```
  133. ---
  134. ### Cursor
  135. Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
  136. ```json
  137. {
  138. "mcpServers": {
  139. "tailscale": {
  140. "command": "npx",
  141. "args": ["-y", "@hexsleeves/tailscale-mcp-server"],
  142. "env": {
  143. "TAILSCALE_API_KEY": "tskey-api-...",
  144. "TAILSCALE_TAILNET": "-"
  145. }
  146. }
  147. }
  148. }
  149. ```
  150. ---
  151. ## Tool Reference
  152. ### Devices
  153. | Tool | Description | Min risk |
  154. |------|-------------|----------|
  155. | `list_devices` | List all devices in the configured tailnet | `read` |
  156. | `device_action` | Authorize or expire a device key (`write`); deauthorize or delete (`admin`) | `write` / `admin` |
  157. | `manage_routes` | Enable or disable advertised routes for a device | `write` |
  158. ### Network
  159. | Tool | Description | Min risk |
  160. |------|-------------|----------|
  161. | `get_network_status` | Get current Tailscale network status via local CLI | `read` |
  162. | `connect_network` | Connect this host to Tailscale with optional CLI flags | `admin` |
  163. | `disconnect_network` | Disconnect this host from Tailscale | `admin` |
  164. | `ping_peer` | Ping a Tailscale peer through the local CLI | `read` |
  165. | `get_version` | Get local Tailscale CLI version information | `read` |
  166. ### Administration
  167. | Tool | Description | Min risk |
  168. |------|-------------|----------|
  169. | `get_tailnet_info` | Get detailed information about the configured tailnet | `read` |
  170. | `manage_file_sharing` | Read (`read`) or update (`write`) tailnet file sharing settings | `read` / `write` |
  171. | `manage_exit_nodes` | List exit nodes (`read`); set, clear, advertise, or stop advertising (`admin`) | `read` / `admin` |
  172. | `manage_webhooks` | List webhooks (`read`); create, delete, or test webhooks (`write`) | `read` / `write` |
  173. | `manage_device_tags` | Read (`read`) or update (`write`) tags for a device | `read` / `write` |
  174. | `get_version_info` | Return server version identifier | `read` |
  175. ### ACL and Policy
  176. | Tool | Description | Min risk |
  177. |------|-------------|----------|
  178. | `manage_acl` | Read (`read`), validate, or update (`write`) the tailnet ACL policy | `read` / `write` |
  179. | `manage_dns` | Read (`read`) or update (`write`) Tailscale DNS settings | `read` / `write` |
  180. | `manage_keys` | List auth keys (`read`); create or delete (`admin`) | `read` / `admin` |
  181. | `manage_policy_file` | Read (`read`) or update (`write`) the tailnet policy file | `read` / `write` |
  182. | `manage_network_lock` | Network lock status (`read`) and mutation operations (`admin`) | `read` / `admin` |
  183. ---
  184. ## Resources and Prompts
  185. ### Resources (read-only)
  186. | URI | Description |
  187. |-----|-------------|
  188. | `tailscale://tailnet/summary` | High-level tailnet summary |
  189. | `tailscale://devices` | All devices in the tailnet |
  190. | `tailscale://devices/{deviceId}` | Detail for a single device |
  191. | `tailscale://acl/current` | Current ACL policy |
  192. ### Prompts
  193. | Name | Description |
  194. |------|-------------|
  195. | `diagnose_tailnet_connectivity` | Guided diagnostic for connectivity issues |
  196. | `review_acl_change` | Structured review workflow for ACL policy changes |
  197. ---
  198. ## Configuration
  199. | Variable | Default | Description |
  200. |----------|---------|-------------|
  201. | `TAILSCALE_OAUTH_CLIENT_ID` | — | OAuth client ID (preferred auth method) |
  202. | `TAILSCALE_OAUTH_CLIENT_SECRET` | — | OAuth client secret (required with `CLIENT_ID`) |
  203. | `TAILSCALE_API_KEY` | — | Legacy API key fallback |
  204. | `TAILSCALE_TAILNET` | `-` | Tailnet name or `-` shorthand for the default tailnet |
  205. | `TAILSCALE_API_BASE_URL` | `https://api.tailscale.com` | Tailscale API base URL (https required except for localhost) |
  206. | `TAILSCALE_ALLOWED_TOOL_RISK` | `read` | Maximum allowed tool risk: `read`, `write`, or `admin` |
  207. | `TAILSCALE_CLI_PATH` | `tailscale` | Path to the local Tailscale CLI binary |
  208. | `MCP_TRANSPORT` | `stdio` | Transport mode: `stdio` or `http` |
  209. | `MCP_HTTP_BIND_HOST` | `127.0.0.1` | Host to bind in HTTP mode |
  210. | `MCP_HTTP_PORT` | `3000` | Port to bind in HTTP mode |
  211. | `MCP_HTTP_BEARER_TOKEN` | — | Required for HTTP mode (minimum 32 characters) |
  212. | `MCP_ALLOWED_HOSTS` | — | Comma-separated additional allowed HTTP Host header values |
  213. | `LOG_LEVEL` | `info` | Log verbosity: `debug`, `info`, `warn`, or `error` |
  214. | `MCP_SERVER_LOG_FILE` | — | Optional file path for log output |
  215. ### Risk levels
  216. - `read` — list devices, inspect status, read resources, run diagnostics.
  217. - `write` — update ACLs, DNS, routes, policy files, webhooks, tags, and other mutating settings.
  218. - `admin` — destructive or host-affecting operations: delete, deauthorize, connect, disconnect, auth key mutation, file sharing changes, exit node control.
  219. ---
  220. ## HTTP Transport
  221. HTTP mode is intended for private tailnet access. It requires `MCP_HTTP_BEARER_TOKEN` and binds to `127.0.0.1` by default.
  222. ```bash
  223. export MCP_TRANSPORT=http
  224. export MCP_HTTP_BEARER_TOKEN="$(openssl rand -base64 32)"
  225. export TAILSCALE_OAUTH_CLIENT_ID="your-client-id"
  226. export TAILSCALE_OAUTH_CLIENT_SECRET="your-client-secret"
  227. export TAILSCALE_TAILNET="-"
  228. npx -y @hexsleeves/tailscale-mcp-server --http --host 127.0.0.1 --port 3000
  229. ```
  230. Expose privately with Tailscale Serve (recommended for tailnet deployments):
  231. ```bash
  232. tailscale serve --bg 443 localhost:3000
  233. ```
  234. Do not use Tailscale Funnel for normal MCP operation. Funnel makes the endpoint publicly reachable on the internet.
  235. A `GET /health` endpoint returns `200 OK` when the server is running.
  236. For full Docker sidecar deployment instructions, see [docs/docker.md](docs/docker.md).
  237. ---
  238. ## Docker
  239. ### Run with Docker Hub image
  240. ```bash
  241. docker run --rm \
  242. -e TAILSCALE_API_KEY="tskey-api-..." \
  243. -e TAILSCALE_TAILNET="-" \
  244. -p 127.0.0.1:3000:3000 \
  245. hexsleeves/tailscale-mcp-server:latest
  246. ```
  247. ### Run with GHCR image
  248. ```bash
  249. docker run --rm \
  250. -e TAILSCALE_API_KEY="tskey-api-..." \
  251. -e TAILSCALE_TAILNET="-" \
  252. -p 127.0.0.1:3000:3000 \
  253. ghcr.io/hexsleeves/tailscale-mcp-server:latest
  254. ```
  255. ### Build locally
  256. ```bash
  257. docker build -t tailscale-mcp-server .
  258. ```
  259. For sidecar deployment with Tailscale Serve, see [docs/docker.md](docs/docker.md).
  260. ---
  261. ## Example Prompts
  262. Once the server is connected to your MCP client, try these:
  263. - "List my Tailscale devices and show which ones are offline."
  264. - "What is the current Tailscale network status on this machine?"
  265. - "Diagnose connectivity to my NAS at 100.64.0.5."
  266. - "Show me the current ACL policy for my tailnet."
  267. - "Review this ACL change before I apply it." *(attach the new policy)*
  268. - "What DNS nameservers is my tailnet using?"
  269. - "List all active webhooks in my tailnet."
  270. ---
  271. ## Development
  272. ```bash
  273. # Install dependencies (Bun required for development)
  274. bun install
  275. # Type check
  276. bun run typecheck
  277. # Run tests
  278. bun test
  279. # Lint and format
  280. bun run check
  281. # Build
  282. bun run build
  283. # Full verification (typecheck + lint + test + build)
  284. bun run qa:full
  285. # Security audit
  286. bun audit
  287. ```
  288. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development workflow, commit conventions, and release process.
  289. ---
  290. ## Contributing
  291. Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
  292. - [CONTRIBUTING.md](CONTRIBUTING.md) — development setup, commit conventions, PR process.
  293. - [SECURITY.md](SECURITY.md) — responsible disclosure policy.
  294. - [LICENSE](LICENSE) — MIT.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.