Provides tools for managing and monitoring a Tailscale tailnet, including listing devices with connectivity status, IPs, and latency, and performing connectivity probes such as ping, port checks, and SSH validation via the local CLI or REST API.
Enables control and diagnostics over a WireGuard-based mesh network through Tailscale integration, supporting device discovery and connectivity checks across mesh peers.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@tailscale-mesh-mcp ping 100.101.102.103 to see if it’s online"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A production-grade, zero-trust Model Context Protocol (MCP) server providing AI assistants direct, authenticated control over a private Tailscale / WireGuard mesh network.
Built with TypeScript, @modelcontextprotocol/sdk, and Zod, featuring a dual-backend architecture that unifies the local tailscale CLI engine with the Tailscale v2 REST API.
+---------------------------------------+
| AI Host (Claude, Cursor, AGY, etc.) |
+---------------------------------------+
|
JSON-RPC (stdio)
|
+---------------------------------------+
| tailscale-mesh-mcp |
+---------------------------------------+
/ \
(Local Fast-Path / CLI) (Fallback / Remote Admin)
/ \
v v
+-----------------------+ +------------------------+
| tailscale daemon/CLI | | Tailscale REST API v2 |
| (execFile argument-vec| | (Bearer auth fetch) |
+-----------------------+ +------------------------+
| |
+---------------+---------------+
|
v
+-----------------------+
| Tailscale Mesh Tailnet|
+-----------------------+Stdio Protocol Isolation: Strictly streams structured diagnostics to process.stderr, preserving process.stdout exclusively for JSON-RPC message framing.
Dual-Engine Auto-Discovery: Queries the local tailscale binary by default (zero cloud rate limits, sub-millisecond status), transparently falling back to the Tailscale REST API when running on remote instances or when daemon access is unavailable.
Zero Command Injection: Disallows shell interpolation. All binary executions utilize execFile with sanitized argument vectors (string[]) and RFC 1123 / IP validation.
Safe Dry-Run Modes: Operators and AI agents can simulate network operations, latency checks, and configuration alterations before affecting live node state.
Related MCP server: tailscale-blade-mcp
tailscale-mesh-mcp/
├── .env.example # Template for environment configuration
├── .gitignore # Git ignore rules
├── package.json # Dependencies and build scripts
├── tsconfig.json # TypeScript compiler settings (NodeNext)
├── tsup.config.ts # Fast ESM bundle configuration
├── README.md # Project documentation
└── src/
├── index.ts # MCP Server entrypoint & tool schema registration
├── tailscale/
│ ├── client.ts # Unified dual-engine Tailscale client (CLI + REST)
│ └── types.ts # Strongly typed domain models (Device, Peer, API)
└── utils/
├── logger.ts # Safe stderr-only logger for MCP Stdio compatibility
└── validator.ts # Hostname, IPv4, IPv6, and Port security validationlist_devicesDiscovers all nodes across the mesh tailnet with connectivity status, OS details, IP allocations, and latency telemetry.
Parameters:
source ("auto" | "cli" | "api"): Select data backend (default: "auto").
status ("all" | "online" | "offline"): Filter nodes by presence (default: "all").
check_connectivityPerforms active network diagnostics across mesh peers using latency probes (tailscale ping), TCP socket reachability checks, or safe SSH validation.
Parameters:
type ("ping" | "port" | "ssh"): Probe type.
target: Target node Tailscale IP (e.g. 100.100.1.2), MagicDNS name (node.tailnet.ts.net), or hostname.
port (number, 1-65535): Required when type is "port".
count (number, 1-10): Ping packet count (default: 3).
timeoutMs (number, 500-30000): Probe timeout in ms (default: 5000).
sshCommand (string): Safe command executed via Tailscale SSH (default: "exit 0").
dryRun (boolean): Simulates the check and validates arguments without initiating network packets.
Node.js >= 18.0.0
A Tailscale account and/or local tailscale CLI installed
git clone https://github.com/R-zin/tailscale-mesh-mcp.git
cd tailscale-mesh-mcp
# Install dependencies
npm install
# Compile TypeScript and bundle ESM binary
npm run buildVariable | Description | Default |
| Tailscale API access token ( | Optional (required for REST fallback) |
| Tailnet name or |
|
| Explicit path to | Auto-detected from PATH / OS locations |
| Logging level ( |
|
claude_desktop_config.json){
"mcpServers": {
"tailscale": {
"command": "node",
"args": ["/absolute/path/to/tailscale-mesh-mcp/dist/index.js"],
"env": {
"TAILSCALE_API_KEY": "tskey-api-...",
"TAILSCALE_TAILNET": "-"
}
}
}
}Phase 1: Core runtime, CLI/REST dual-engine client, list_devices, check_connectivity.
Phase 2: manage_funnel (dynamic port exposure & unexposure with safety controls).
Phase 3: audit_acl_rules (HuJSON ACL parser, policy validation, diff preview).
Phase 4: NetBird mesh VPN provider adapter.
Execute internal network latency pings (tailscale ping), TCP port tests, or SSH health checks across mesh nodes.
| Name | Required | Description | Default |
|---|---|---|---|
| port | No | Target TCP port number (required if type is 'port') | |
| type | Yes | Check type: 'ping' for WireGuard/DERP latency, 'port' for TCP socket test, or 'ssh' for Tailscale SSH verification | |
| count | No | Number of ping packets to send (for ping type, default 3) | |
| dryRun | No | Simulate the connectivity check without executing network commands or connections | |
| target | Yes | Target node Tailscale IP address (100.x.y.z), MagicDNS name (node.tailnet.ts.net), or hostname | |
| timeoutMs | No | Timeout in milliseconds for the connectivity probe (default 5000ms) | |
| sshCommand | No | Safe command to execute over Tailscale SSH (for ssh type, default: 'exit 0') | exit 0 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, yet it only says these checks are 'executed.' It does not disclose that it runs active network commands against remote mesh nodes, that the ssh mode can execute a command on a target host, whether credentials/permissions are required, or what side effects or failures look like.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single tight sentence with the verb front-loaded and no filler; the parenthetical '(tailscale ping)' earns its place by disambiguating the ping mode. The three modes are run together rather than structured as a list, which is the only minor weakness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter tool with no annotations and no output schema, the description is thin: it says nothing about what a check returns (latency figures, success/failure, raw output), nothing about authentication or prerequisites for SSH, and nothing about the dryRun simulation path. An agent would have to rely entirely on the schema to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter (type enum, port, count, dryRun, timeoutMs, sshCommand) is already documented in the schema. The description adds no format, default, or constraint detail beyond it, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb (execute) and resource (network latency pings / TCP port tests / SSH health checks) and enumerates the three supported modes. It is unambiguous on its own, but it offers no explicit contrast with the only sibling, list_devices.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Enumerating the three check types ('ping', 'port', 'ssh') implies which mode to pick for which scenario, but there is no explicit when-to-use/when-not statement and no routing to alternatives. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List nodes on the Tailscale mesh network with online status, OS, Tailscale IPv4/IPv6 addresses, tags, and last seen timestamps.
| Name | Required | Description | Default |
|---|---|---|---|
| source | No | Backend query source: 'cli' (local daemon), 'api' (Tailscale REST API v2), or 'auto' (tries CLI, falls back to API) | auto |
| status | No | Filter devices by connectivity status ('all', 'online', or 'offline') | all |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It lists returned fields such as online status and IP addresses, but does not disclose read-only safety, authentication requirements, rate limits, pagination, or source fallback behavior, leaving significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The definition is a single front-loaded sentence with no filler. Every part of the sentence contributes to describing the resource and the information returned.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity and 100% schema coverage, the description is adequate for a simple list operation and usefully summarizes return fields since no output schema exists. However, it omits usage guidance and behavioral context, leaving clear gaps for an agent selecting and invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both parameters have enum descriptions in the schema, so the baseline is 3. The description adds no parameter-level meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb ('List') and specific resource ('nodes on the Tailscale mesh network') and enumerates returned fields, which helps an agent understand what the tool provides. It does not explicitly distinguish this tool from the sibling check_connectivity, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no when-to-use guidance, no exclusions, and no comparison to the sibling tool check_connectivity. An agent can infer that this lists devices, but the definition provides no routing context for choosing it over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0check_connectivitylist_devicesScored across 2 tools
The two tools have clearly distinct purposes: listing devices on the mesh versus checking connectivity (ping/TCP/SSH). There is no overlap in functionality or resource targets.
Both names follow a consistent verb_noun snake_case pattern: list_devices and check_connectivity. The convention is predictable and easy to parse.
Two tools is borderline thin for a Tailscale mesh server; while they cover basic monitoring, most mesh-related servers would offer more operations (e.g., device management, network status).
The surface covers listing devices and connectivity checks, which are core read operations. However, notable gaps exist: no tool to retrieve a single device's details, no write operations (tagging, deleting), and no network topology or ACL inspection.
Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.
Gives AI agents a public IPv6 identity, hostname, port forwarding, web fetch, team mesh. Free tier.
Query your team's drift, vulnerability, and upgrade data from any AI assistant. OAuth 2.1, 51 tools.
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
