Tailscale — Claude Code MCP server: what it does, how to install
Controls local Tailscale nodes through the CLI and manages the tailnet via the control-plane API. Gives AI coding agents direct access to network state.
claude mcp add --env TAILSCALE_API_KEY=<TAILSCALE_API_KEY> --env TAILSCALE_OAUTH_CLIENT_ID=<TAILSCALE_OAUTH_CLIENT_ID> --env TAILSCALE_OAUTH_CLIENT_SECRET=<TAILSCALE_OAUTH_CLIENT_SECRET> --env TAILSCALE_TAILNET=<TAILSCALE_TAILNET> --env TAILSCALE_MCP_PRESET=<TAILSCALE_MCP_PRESET> --transport stdio tailscale -- npx -y @tailscale-mcp/tailscale-mcpWhat Tailscale does
This server connects an AI assistant to Tailscale infrastructure. It runs local node operations by calling the tailscale CLI directly and executes wider tailnet changes using the control-plane REST API. Each plane works independently. If no credentials are supplied, network-wide tools stay hidden while local node tools remain available.
Tools are grouped into minimal, core, and full presets. Dangerous actions stay restricted by default. Read operations are always enabled, but configuration edits and destructive actions demand explicit permission flags. Tailnet-wide destructive calls also mandate passing confirm: true.
On macOS, the server requires the shim installed at /usr/local/bin. Pointing directly to the binary inside the application bundle launches the GUI instead of answering CLI calls, causing all node tools to fail.
What it helps with
- inspect node status and active devices across the tailnet
- modify device routing and tailnet configuration through the REST API
- restrict agent execution to read-only network inspection
- verify environment tools and credentials using
tailscale-mcp diagnose
Example prompts for the agent
- List all reachable devices currently active in my tailnet
- Check the connection status of this local Tailscale node
- Run
tailscale-mcp diagnoseto see which tool sets are currently enabled
How to install Tailscale
Platform CLI
claude mcp add --env TAILSCALE_API_KEY=<TAILSCALE_API_KEY> --env TAILSCALE_OAUTH_CLIENT_ID=<TAILSCALE_OAUTH_CLIENT_ID> --env TAILSCALE_OAUTH_CLIENT_SECRET=<TAILSCALE_OAUTH_CLIENT_SECRET> --env TAILSCALE_TAILNET=<TAILSCALE_TAILNET> --env TAILSCALE_MCP_PRESET=<TAILSCALE_MCP_PRESET> --transport stdio tailscale -- npx -y @tailscale-mcp/tailscale-mcpReplace <…> with your own values. 2 more environment variables are in the server README
Platform CLI
codex mcp add tailscale --env TAILSCALE_API_KEY=<TAILSCALE_API_KEY> --env TAILSCALE_OAUTH_CLIENT_ID=<TAILSCALE_OAUTH_CLIENT_ID> --env TAILSCALE_OAUTH_CLIENT_SECRET=<TAILSCALE_OAUTH_CLIENT_SECRET> --env TAILSCALE_TAILNET=<TAILSCALE_TAILNET> --env TAILSCALE_MCP_PRESET=<TAILSCALE_MCP_PRESET> -- npx -y @tailscale-mcp/tailscale-mcpReplace <…> with your own values. 2 more environment variables are in the server README
Config file
{
"mcpServers": {
"tailscale": {
"command": "npx",
"args": [
"-y",
"@tailscale-mcp/tailscale-mcp"
],
"env": {
"TAILSCALE_API_KEY": "<TAILSCALE_API_KEY>",
"TAILSCALE_OAUTH_CLIENT_ID": "<TAILSCALE_OAUTH_CLIENT_ID>",
"TAILSCALE_OAUTH_CLIENT_SECRET": "<TAILSCALE_OAUTH_CLIENT_SECRET>",
"TAILSCALE_TAILNET": "<TAILSCALE_TAILNET>",
"TAILSCALE_MCP_PRESET": "<TAILSCALE_MCP_PRESET>"
}
}
}
}Replace <…> with your own values. 2 more environment variables are in the server README
Config file
{
"servers": {
"tailscale": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@tailscale-mcp/tailscale-mcp"
],
"env": {
"TAILSCALE_API_KEY": "<TAILSCALE_API_KEY>",
"TAILSCALE_OAUTH_CLIENT_ID": "<TAILSCALE_OAUTH_CLIENT_ID>",
"TAILSCALE_OAUTH_CLIENT_SECRET": "<TAILSCALE_OAUTH_CLIENT_SECRET>",
"TAILSCALE_TAILNET": "<TAILSCALE_TAILNET>",
"TAILSCALE_MCP_PRESET": "<TAILSCALE_MCP_PRESET>"
}
}
}
}Replace <…> with your own values. 2 more environment variables are in the server README
Platform CLI
gemini mcp add -e TAILSCALE_API_KEY=<TAILSCALE_API_KEY> -e TAILSCALE_OAUTH_CLIENT_ID=<TAILSCALE_OAUTH_CLIENT_ID> -e TAILSCALE_OAUTH_CLIENT_SECRET=<TAILSCALE_OAUTH_CLIENT_SECRET> -e TAILSCALE_TAILNET=<TAILSCALE_TAILNET> -e TAILSCALE_MCP_PRESET=<TAILSCALE_MCP_PRESET> tailscale npx -y @tailscale-mcp/tailscale-mcpReplace <…> with your own values. 2 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Tailscale
How to install Tailscale in Claude Code?
Run `claude mcp add --env TAILSCALE_API_KEY=<TAILSCALE_API_KEY> --env TAILSCALE_OAUTH_CLIENT_ID=<TAILSCALE_OAUTH_CLIENT_ID> --env TAILSCALE_OAUTH_CLIENT_SECRET=<TAILSCALE_OAUTH_CLIENT_SECRET> --env TAILSCALE_TAILNET=<TAILSCALE_TAILNET> --env TAILSCALE_MCP_PRESET=<TAILSCALE_MCP_PRESET> --transport stdio tailscale -- npx -y @tailscale-mcp/tailscale-mcp`.
What does the Tailscale MCP server do?
It exposes up to 186 tools for interacting with a local Tailscale node via its CLI and the broader tailnet via control-plane API calls.
Why use OAuth credentials instead of an API access token?
OAuth belongs to the tailnet rather than a person, limits permissions to assigned scopes, and issues short-lived tokens valid for one hour.
