Lets AI agents discover tailnet nodes, generate SSH configurations, manage port sharing via Serve/Funnel, and analyze network latency.
Also known as TMHSDigital/tailscale-mcp, tailscale-mcp, @tmhs/tailscale-mcp
- Stars
- 1
- Tools
- 10
- Downloads, 30 days
- —
- Latest version
- 0.4.0
- Last commit
- Nov 10, 2026
- License
- —
What is Tailscale MCP?
Tailscale lets AI agents discover tailnet nodes, generate SSH configurations, manage port sharing via Serve/Funnel, and analyze network latency. It exposes 10 tools, such as tailnet_status, share_status, ping_all.
Summary generated from the project's README
About Tailscale MCP server
Tailscale MCP provides a structured interface for AI agents to interact with a local Tailscale daemon via stdio. It functions by executing the tailscale CLI already present on your system, meaning it does not handle sensitive authentication keys or credentials directly. This server is designed for developers using clients like Claude Desktop, Cursor, or VS Code to automate network management tasks safely.
Users can perform network discovery, generate SSH configurations, and manage port sharing through Serve and Funnel. The server includes safety features such as a read-only mode and a specific environment variable to prevent accidental public exposure via Funnel. It also provides detailed latency matrices to help agents understand if connections are direct or relayed. Because it relies on the local CLI, it works across Windows and macOS, including Mac App Store installations, provided the Tailscale client is logged in.
What you can do with it
- 1Automate SSH configurationAn agent can generate and write SSH Host blocks for your tailnet nodes to simplify remote access.
- 2Share local servicesYou can instruct an AI to expose a local development port to your tailnet or the public internet.
- 3Analyze network connectivityA developer can ask an agent to check the reachability and latency of all nodes in the network.
Written from the project's README. Every use case is checked against a quote from it.
How to install Tailscale MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Tailscale MCP in Claude Code
$ claude mcp add tailscale-mcp -- npx -y @tmhs/tailscale-mcpInstall Tailscale MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"tailscale-mcp": {
"command": "npx",
"args": [
"-y",
"@tmhs/tailscale-mcp"
]
}
}
}Install Tailscale MCP in VS Code
.vscode/mcp.json
{
"servers": {
"tailscale-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@tmhs/tailscale-mcp"
]
}
}
}Install Tailscale MCP in VS Code CLI
$ code --add-mcp '{"name":"tailscale-mcp","type":"stdio","command":"npx","args":["-y","@tmhs/tailscale-mcp"]}'Install Tailscale MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"tailscale-mcp": {
"command": "npx",
"args": [
"-y",
"@tmhs/tailscale-mcp"
]
}
}
}Install Tailscale MCP in Codex
$ codex mcp add tailscale-mcp -- npx -y @tmhs/tailscale-mcpInstall Tailscale MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.tailscale-mcp] command = "npx" args = ["-y", "@tmhs/tailscale-mcp"]
Install Tailscale MCP in Gemini CLI
$ gemini mcp add -s user tailscale-mcp npx -- -y @tmhs/tailscale-mcpInstall Tailscale MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"tailscale-mcp": {
"command": "npx",
"args": [
"-y",
"@tmhs/tailscale-mcp"
]
}
}
}Tailscale MCP tools 10
Detected from the READMEtailnet_statusshare_statusping_allgenerate_ssh_configshare_portstop_sharewritetargetmineall
| tailnet_status | — | |
| share_status | — | |
| ping_all | — | |
| generate_ssh_config | — | |
| share_port | — | |
| stop_share | — | |
| write | — | |
| target | — | |
| mine | — | |
| all | — |
Configuration
TAILSCALE_MCP_ALLOW_FUNNELSet to 1 to let share_port expose a port to the open internet with Funnel (off by default)
TAILSCALE_MCP_BINPath to the tailscale binary if it is not on PATH or in the default install location
TAILSCALE_MCP_READONLYSet to 1 for monitoring only: no share tools, and no SSH config writes
TAILSCALE_MCP_TIMEOUT_MSPer-call timeout for tailscale commands in milliseconds (default 10000)
| Name | Description | |
|---|---|---|
| TAILSCALE_MCP_ALLOW_FUNNEL | Set to 1 to let share_port expose a port to the open internet with Funnel (off by default) | |
| TAILSCALE_MCP_BIN | Path to the tailscale binary if it is not on PATH or in the default install location | |
| TAILSCALE_MCP_READONLY | Set to 1 for monitoring only: no share tools, and no SSH config writes | |
| TAILSCALE_MCP_TIMEOUT_MS | Per-call timeout for tailscale commands in milliseconds (default 10000) |
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work · What to fix for more points
- Source repository linked and reachabletmhsdigital/tailscale-mcp is public and reachablegithub.com/tmhsdigital/tailscale-mcp ↗Pass
- Package names this repository as its source@tmhs/tailscale-mcp names tmhsdigital/tailscale-mcp as sourcenpmjs.com/package/@tmhs/tailscale-mcp ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @tmhs/tailscale-mcpnpmjs.com/package/@tmhs/tailscale-mcp/v/0.4.0#provenance ↗Pass
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-11-10github.com/tmhsdigital/tailscale-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @tmhs/tailscale-mcpPass
- No critical advisory in the package or its dependencies99 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model10 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubTailscale MCP
MCP server for safe programmatic access to the local Tailscale daemon: tailnet discovery, SSH config generation, port sharing via Serve/Funnel, and latency matrices.
Gives agents and developer tools a safe, structured window into the local Tailscale daemon over stdio. It shells out to the tailscale CLI (resolved from PATH, with fallbacks to the default install locations on Windows and macOS) and never handles auth keys or tailnet credentials: the CLI talks to the already-authenticated local daemon.
When the binary is missing, the daemon is stopped, or the device needs login, every tool returns a structured error with a code and the exact remedy command instead of throwing.
Installation
- Claude Code:
claude mcp add tailscale -- npx -y @tmhs/tailscale-mcp - Claude Desktop: download
tailscale-mcp.mcpbfrom the latest release and open it. The install dialog has switches for read-only mode and Funnel. - Cursor / VS Code: use the buttons above.
- MCP Registry: listed in the official MCP Registry as
io.github.TMHSDigital/tailscale-mcp, so registry-aware clients and catalogs can find it.
Or add it to any MCP client's configuration by hand:
{
"mcpServers": {
"tailscale": {
"command": "npx",
"args": ["-y", "@tmhs/tailscale-mcp"]
}
}
}
Requires Node 22+ (an active LTS) and an installed, logged-in Tailscale client.
Finding the tailscale CLI
The server looks for tailscale on PATH, then in the platform's default install locations: C:\Program Files\Tailscale\tailscale.exe on Windows, and /Applications/Tailscale.app/Contents/MacOS/Tailscale, /opt/homebrew/bin/tailscale, and /usr/local/bin/tailscale on macOS. Mac App Store installs therefore work without extra setup. To use a different binary, set TAILSCALE_MCP_BIN:
{
"mcpServers": {
"tailscale": {
"command": "npx",
"args": ["-y", "@tmhs/tailscale-mcp"],
"env": { "TAILSCALE_MCP_BIN": "/path/to/tailscale" }
}
}
}
Timeouts
Every tailscale invocation is bounded, by default to 10 seconds. A hung daemon returns a structured TIMEOUT error instead of stalling the agent. Set TAILSCALE_MCP_TIMEOUT_MS to raise the limit for slow machines or very large tailnets. share_port waits up to 15 seconds and ping scales with count and timeoutMs; ping_all as a whole is capped at 45 seconds.
Configuration reference
All settings are environment variables in the server's env block. Boolean flags accept 1/true/yes/on or 0/false/no/off. Any other value stops the server at startup, so a typo can never silently loosen a safety setting.
| Variable | Default | Effect |
|---|---|---|
TAILSCALE_MCP_ALLOW_FUNNEL |
off | Allows share_port {"public": true}, which exposes a port to the open internet via Funnel. While off, the call returns FUNNEL_DISABLED and nothing is shared. |
TAILSCALE_MCP_READONLY |
off | Monitoring-only mode: share_port and stop_share are not registered, and generate_ssh_config refuses write: true (READ_ONLY). |
TAILSCALE_MCP_BIN |
(search) | Path to the tailscale binary. |
TAILSCALE_MCP_TIMEOUT_MS |
10000 |
Per-call CLI timeout. |
Linux: Serve/Funnel permissions
On Linux only root or the configured operator can change Serve/Funnel settings. If share_port or stop_share returns PERMISSION_DENIED, allow your user once:
sudo tailscale set --operator=$USER
Tools
Every tool declares MCP annotations, so clients can auto-approve the read-only ones and confirm the rest. Results come back as structuredContent, typed by each tool's outputSchema, with the same JSON repeated in a text block for older clients. The full definitions are in mcp-tools.json, which is generated from the server.
| Tool | Read-only | Destructive | Idempotent | Open world |
|---|---|---|---|---|
tailnet_status |
yes | no | yes | no |
share_status |
yes | no | yes | no |
ping_all |
yes | no | yes | no |
generate_ssh_config |
no (writes only with write: true) |
no | yes | no |
share_port |
no | no | yes | only when Funnel is allowed |
stop_share |
no | yes | yes | no |
tailnet_status
Trimmed view of tailscale status --json: self node plus peers with hostname, MagicDNS name, Tailscale IPv4/IPv6, OS, online flag, last seen, exit-node flags, and tags. Input: optional onlineOnly.
{
"backendState": "Running",
"tailnet": "user@example.com",
"magicDNSSuffix": "tail1234.ts.net",
"self": {"hostname": "DEVPC", "dnsName": "devpc.tail1234.ts.net", "ipv4": "100.101.1.10"},
"peerCount": 3,
"peers": [
{"hostname": "raspi", "dnsName": "raspi.tail1234.ts.net", "ipv4": "100.101.1.20", "os": "linux", "online": true, "exitNodeOption": true, "tags": []}
]
}
generate_ssh_config
Emits ssh-config Host blocks for tailnet nodes (MagicDNS name preferred, Tailscale IP fallback). Dry-run by default: returns the generated text only. Inputs: write, target, onlineOnly, includeShared, user.
- Each
Hostalias is the node's first MagicDNS label (raspi.tail1234.ts.net→raspi), falling back to a sanitized OS hostname ([a-z0-9-]only). Colliding aliases get a numeric suffix and are listed underrenamed. Mullvad exit nodes, and nodes of users you share with (unlessincludeShared: true), are left out and listed underskipped. write: truewrites the dedicated file~/.ssh/tailscale_dev_configand returns theInclude tailscale_dev_configinstruction for~/.ssh/config(never applied automatically).target: "user_ssh_config"(withwrite: true) edits~/.ssh/configdirectly, idempotently, between# BEGIN tailscale-mcpand# END tailscale-mcpmarkers. Content outside the markers is never touched. If the markers are malformed (orphaned, reversed, or duplicated) the tool returnsSSH_CONFIG_MARKERS_CORRUPTand writes nothing.- Writes are atomic (temp file + rename), the previous
~/.ssh/configis kept asconfig.tailscale-mcp.bak, new files are created0600(existing modes are kept), and a symlinked config is written through rather than replaced.
{
"dryRun": true,
"hostCount": 2,
"configText": "# BEGIN tailscale-mcp\nHost raspi\n HostName raspi.tail1234.ts.net\n\nHost devbox\n HostName devbox.tail1234.ts.net\n# END tailscale-mcp"
}
share_port
Shares a local port via Tailscale Serve. Tailnet-only by default. Inputs: port (required), public, path.
{"port": 3000, "public": false, "scope": "tailnet-only (Serve)", "urls": ["https://devpc.tail1234.ts.net/"]}
public: true switches to Funnel and exposes the port to the open internet. It's refused unless TAILSCALE_MCP_ALLOW_FUNNEL=1 is set; see the security notes below.
share_status
Reports active Serve/Funnel sessions as structured endpoints, parsed from tailscale serve status --json. Each endpoint has its own public flag, which is true when Funnel exposes it to the internet, and publicExposure is true when anything is public:
{
"active": true,
"publicExposure": true,
"endpoints": [
{"url": "https://devpc.tail1234.ts.net/", "host": "devpc.tail1234.ts.net", "httpsPort": 443, "scheme": "https", "path": "/", "target": "http://127.0.0.1:3000", "targetType": "proxy", "public": true, "foreground": false}
]
}
Raw TCP forwards appear under tcpForwards. On CLIs too old for --json, the text status comes back under status and publicExposure is null.
stop_share
Stops shares. Name exactly one target:
httpsPortand/orpathturns off one mount.httpsPortis the serve port shown inshare_status(default 443, not the proxied local port), andpathis the mount path given toshare_port(default/). For example,{"path": "/api"}undoesshare_port {"port": 3000, "path": "/api"}.mine: truestops only the sharesshare_portcreated during this server session.all: trueclears the entire serve/funnel configuration, including shares you set up outside this server.
With no arguments nothing is stopped: the tool returns TARGET_REQUIRED and lists the active endpoints. Every successful call returns removed (the endpoints that went away) and remaining (the share_status view afterwards).
Mount paths must start with / and use only letters, digits, and . _ ~ - /, with no . or .. segments. A trailing slash is dropped.
ping_all
Concurrent tailscale ping against peers (bounded to 5 in flight, with a per-ping timeout). Inputs: count, timeoutMs, onlineOnly (default true).
{
"pinged": 2,
"reachable": 1,
"timedOut": false,
"matrix": [
{"hostname": "raspi", "target": "100.101.1.20", "reachable": true, "latencyMs": 3, "path": "direct", "via": "192.168.1.20:41641", "attempts": 3, "replies": 3},
{"hostname": "exitbox", "target": "100.101.1.40", "reachable": false, "latencyMs": null, "path": null, "via": null, "attempts": 1, "replies": 0}
]
}
path is direct (peer-to-peer), derp (relayed through a Tailscale DERP server), peer-relay (relayed through one of your nodes), or unknown, so an agent can tell "works but relayed" from "fast direct path". tailscale ping keeps pinging until a direct path comes up, so path and latencyMs describe the last reply, i.e. the settled path. The whole call is capped at 45 seconds: peers that haven't answered by then come back with an error and timedOut: true.
Agentic workflow example
An agent asked to "deploy this to my dev VPS and show me the result" can do the whole discovery leg through this server:
tailnet_status {"onlineOnly": true}finds the VPS node and its MagicDNS name (devbox.tail1234.ts.net), with no hardcoded IPs.generate_ssh_config {"write": true, "user": "deploy"}writes~/.ssh/tailscale_dev_config; the agent shows the returned one-lineIncludeinstruction, and after the user adds it,ssh devboxresolves through the tailnet.ping_allconfirms the node is reachable and whether the path is direct or relayed before starting a large transfer.- After deploying,
share_port {"port": 8080}returns a tailnet-only URL teammates on the tailnet can open. Nothing touches the public internet unless you have enabled Funnel withTAILSCALE_MCP_ALLOW_FUNNEL=1and the agent is explicitly told to passpublic: true.
Security notes on Funnel
share_portdefaults to tailnet-only Serve. Nothing is reachable from outside your tailnet.- Funnel is off unless you turn it on.
public: trueuses Tailscale Funnel, which makes the URL reachable by anyone on the internet, not just your tailnet. A default install refuses it withFUNNEL_DISABLED, so a prompt-injected agent can't expose a port by itself. To allow it, setTAILSCALE_MCP_ALLOW_FUNNEL=1in the client config. Even then the tool description carries the warning, so agents surface it before acting. TAILSCALE_MCP_READONLY=1removes the share tools entirely, for agents that should only observe.- Serve and Funnel must be enabled per-tailnet in the admin console. When they are not, the tool returns a structured
SERVE_NOT_ENABLEDerror containing the exact enablement URL and changes nothing. stop_share {"all": true}is the kill switch: it clears the entire serve/funnel configuration. Calling it without arguments never deletes anything.- This server never reads or stores
TS_AUTHKEYor any other credential.
Development
npm install
npm run build # tsc
npm test # vitest, fully offline (fixture-driven, no live tailnet)
npm run typecheck # src and tests
npm run gen:tools # regenerate mcp-tools.json after changing a tool
To try your build against your own tailnet, run it in the MCP Inspector:
npm run build
npx @modelcontextprotocol/inspector node dist/index.js
Provider adapter pattern: src/providers/types.ts defines the TailscaleProvider interface; CliProvider (the only implementation today) spawns the CLI through an injectable process runner so tests never launch a real binary. The interface leaves room for a future LocalAPI provider speaking HTTP over the local socket or named pipe.
Project Structure
tailscale-mcp/
src/index.ts stdio entry point
src/config.ts Environment variable parsing
src/providers/ TailscaleProvider interface + CliProvider
src/tools/ MCP tool registrations and output schemas
src/sshconfig.ts Pure ssh-config rendering and managed-block editing
src/__tests__/ vitest suites (offline, mocked CLI runner)
test/fixtures/ Sanitized CLI output used by the tests
mcp-tools.json Generated tool definitions (npm run gen:tools)
docs/ GitHub Pages site
.github/ CI/CD workflows
Roadmap
See ROADMAP.md for the full project roadmap.
Contributing
See CONTRIBUTING.md for guidelines.
License
CC-BY-NC-ND-4.0 -- see LICENSE for details.
Built by TMHSDigital
Tailscale MCP questions
How do I add Tailscale MCP to Claude Code?
Run claude mcp add tailscale-mcp -- npx -y @tmhs/tailscale-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Tailscale MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Tailscale MCP provide?
It exposes 10 tools, including tailnet_status, share_status, ping_all, generate_ssh_config, share_port.
How does the server handle authentication?
The server never handles auth keys or tailnet credentials; it shells out to the local tailscale CLI which communicates with the already-authenticated local daemon.
Can an AI agent expose my local ports to the public internet?
No, by default it only allows tailnet-only sharing. Funnel (public internet access) is disabled unless you explicitly set the TAILSCALE_MCP_ALLOW_FUNNEL environment variable to 1.
What happens if the Tailscale daemon is not running?
The tool will return a structured error containing a specific error code and the exact command needed to fix the issue.