@mcp/tailscale

Full-featured Tailscale MCP server combining API and CLI access for the codespaces infrastructure.

Overview

This MCP server provides comprehensive Tailscale integration by combining:

• Tailscale HTTP API - For management operations (devices, auth keys, ACLs, DNS)
• Tailscale CLI - For networking operations (status, ping, connectivity, up/down)

Features

API Tools

• list_devices - List all devices in the tailnet
• get_device - Get detailed information about a specific device
• create_auth_key - Create a new Tailscale auth key
• list_auth_keys - List all auth keys in the tailnet
• delete_auth_key - Delete a Tailscale auth key

CLI Tools

• status - Get Tailscale status from CLI (includes current node info)
• ping - Ping a Tailscale peer to test connectivity
• nc_status - Check Tailscale network connectivity status
• whois - Lookup information about a Tailscale IP address
• up - Connect to Tailscale with various options
• down - Disconnect from Tailscale

Installation

bun install

Configuration

Set the following environment variables:

# For API operations
export TAILSCALE_API_KEY="tskey-api-..."
export TAILSCALE_TAILNET="your-tailnet.ts.net"

# CLI requires Tailscale to be installed and configured
tailscale up

Usage

As MCP Server

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "tailscale": {
      "command": "node",
      "args": ["/path/to/@mcp/tailscale/dist/index.js"],
      "description": "Tailscale integration - API + CLI tools"
    }
  }
}

Programmatically

import { TailscaleClient } from "./client.js";
import { TailscaleCLI } from "./cli.js";

// API client for management operations
const api = new TailscaleClient();
const devices = await api.listDevices();
const authKey = await api.createAuthKey({
  description: "My new key",
  ephemeral: false,
  reusable: true,
});

// CLI client for networking operations
const cli = new TailscaleCLI();
const status = await cli.status();
const pingResult = await cli.ping("100.1.2.3");

Architecture

@mcp/tailscale
├── src/
│   ├── index.ts    # MCP server entry point
│   ├── client.ts   # Tailscale HTTP API client
│   └── cli.ts      # Tailscale CLI wrapper
├── dist/           # Compiled JavaScript
└── package.json

Development

# Build
bun run build

# Run in watch mode
bun run dev

# Test manually
node dist/index.js

Requirements

• Node.js 20+
• Tailscale CLI installed and configured (for CLI tools)
• Tailscale API key (for API tools)

License

MIT