Tailscale MCP: Connect Tailscale with Claude

A modern Model Context Protocol (MCP) server that provides seamless integration with Tailscale's CLI commands and REST API, enabling automated network management and monitoring through a standardized interface.

• NPM :@hexsleeves/tailscale-mcp-server

• Docker Hub :hexsleeves/tailscale-mcp-server

• GitHub Container Registry :ghcr.io/hexsleeves/tailscale-mcp-server

• Device Management : List, authorize, deauthorize, and manage Tailscale devices

• Network Operations : Connect/disconnect, manage routes, and monitor network status

• Security Controls : Manage ACLs, device tags, and network lock settings

• Modern Architecture : Modular tool system with TypeScript and Zod validation

• CLI Integration : Direct integration with Tailscale CLI commands

• API Integration : REST API support for advanced operations

Run directly without installation:

npx --package=@hexsleeves/tailscale-mcp-server tailscale-mcp-server

npx -y @hexsleeves/tailscale-mcp-server

Note: Method 1 with --package= syntax is more reliable across different npx versions and environments.

Or install globally:

npm install -g @hexsleeves/tailscale-mcp-server
tailscale-mcp-server
docker run -d \
  --name tailscale-mcp \
  -e TAILSCALE_API_KEY=your_api_key \
  -e TAILSCALE_TAILNET=your_tailnet \
  hexsleeves/tailscale-mcp-server:latest
docker run -d \
  --name tailscale-mcp \
  -e TAILSCALE_API_KEY=your_api_key \
  -e TAILSCALE_TAILNET=your_tailnet \
  ghcr.io/hexsleeves/tailscale-mcp-server:latest
docker-compose up -d

Add to your Claude Desktop configuration (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "tailscale": {
      "command": "npx",
      "args": [
        "--package=@hexsleeves/tailscale-mcp-server",
        "tailscale-mcp-server"
      ],
      "env": {
        "TAILSCALE_API_KEY": "your-api-key-here",
        "TAILSCALE_TAILNET": "your-tailnet-name"
      }
    }
  }
}
{
  "mcpServers": {
    "tailscale": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "TAILSCALE_API_KEY=xxxxxxxxxxxxx",
        "-e",
        "TAILSCALE_TAILNET=your-tailnet",
        "hexsleeves/tailscale-mcp-server:latest"
      ]
    }
  }
}
{
  "mcpServers": {
    "tailscale-docker": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "TAILSCALE_API_KEY=xxxxxxxxxxxxx",
        "-e",
        "TAILSCALE_TAILNET=your-tailnet",
        "ghcr.io/hexsleeves/tailscale-mcp-server:latest"
      ]
    }
  }
}
export TAILSCALE_API_KEY="your-api-key"
export TAILSCALE_TAILNET="your-tailnet"

export TAILSCALE_API_BASE_URL="https://api.tailscale.com"

export LOG_LEVEL="1"  # 0=DEBUG, 1=INFO, 2=WARN, 3=ERROR
export MCP_SERVER_LOG_FILE="tailscale-mcp-{timestamp}.log"  # Enable file logging

• list_devices - List all devices in the Tailscale network

• device_action - Perform actions on specific devices (authorize, deauthorize, delete, expire-key)

• manage_routes - Enable or disable routes for devices

• get_network_status - Get current network status from Tailscale CLI

• connect_network - Connect to the Tailscale network

• disconnect_network - Disconnect from the Tailscale network

• ping_peer - Ping a peer device

• get_version - Get Tailscale version information

• get_tailnet_info - Get detailed network information

For local development and testing, clone the repository and set up the development environment:

git clone https://github.com/HexSleeves/tailscale-mcp-server.git
cd tailscale-mcp-server

npm install

npm run build
cp .env.example .env

mkdir -p logs

The .env.example file contains all available configuration options with documentation. Key variables for testing:

• TAILSCALE_API_KEY : Get fromTailscale Admin Console
• TAILSCALE_TAILNET : Your organization/tailnet name
• LOG_LEVEL : Set to0 for debug logging during development
• MCP_SERVER_LOG_FILE : Enable server logging to file
• MCP_LOG_FILE : Enable test script logging to file

For development, configure Claude Desktop to use your local build:

{
  "mcpServers": {
    "tailscale-dev": {
      "command": "node",
      "args": ["/path/to/your/tailscale-mcp-server/dist/index.js"],
      "env": {
        "TAILSCALE_API_KEY": "your-api-key-here",
        "TAILSCALE_TAILNET": "your-tailnet-name",
        "LOG_LEVEL": "0"
      }
    }
  }
}
{
  "mcpServers": {
    "tailscale-dev": {
      "command": "npm",
      "args": ["run", "start"],
      "cwd": "/path/to/your/tailscale-mcp-server",
      "env": {
        "TAILSCALE_API_KEY": "your-api-key-here",
        "TAILSCALE_TAILNET": "your-tailnet-name",
        "LOG_LEVEL": "0"
      }
    }
  }
}
npm run build:dev

npm run build:watch

npm run dev

npm test

npm run test:watch

npm run test:coverage

npm run inspector

npm run lint

npm run format

The project includes an interactive publishing script that handles version bumping and publishing to multiple registries:

npm run publish

./scripts/publish.sh

The script will guide you through:

1. Version Bumping : Choose between patch, minor, major, or skip
2. NPM Publishing : Optionally publish to npm registry
3. Docker Hub : Optionally build and publish Docker images
4. GitHub Container Registry : Optionally publish to GHCR
5. Git Operations : Automatically commit version changes and create tags

• Interactive prompts for each publishing step

• Automatic version bumping with semantic versioning

• Git integration with automatic tagging and commits

• Multi-registry support (npm, Docker Hub, GHCR)

• Safety checks for uncommitted changes

• Colored output for better visibility

• Error handling with proper exit codes

• Performance optimized with pre-calculated version previews

• NPM : Logged in withnpm login and proper access to the package

• Docker Hub : Logged in withdocker login

• GHCR : Logged in withdocker login ghcr.io using a GitHub token

• Git : Clean working directory (or confirmation to proceed with uncommitted changes)

For Docker-based development:

docker build -t tailscale-mcp-dev .

docker run -it --rm \
  -v $(pwd):/app \
  -v /app/node_modules \
  -e TAILSCALE_API_KEY=your_api_key \
  -e TAILSCALE_TAILNET=your_tailnet \
  -e LOG_LEVEL=0 \
  tailscale-mcp-dev

docker-compose -f docker-compose.dev.yml up
src/
├── server.ts              # Main server implementation
├── tools/                 # Modular tool definitions
│   ├── index.ts           # Tool registry system
│   ├── device-tools.ts    # Device management tools
│   └── ...                # Additional tool modules
├── tailscale/             # Tailscale integrations
│   ├── tailscale-api.ts   # REST API client
│   ├── tailscale-cli.ts   # CLI wrapper
│   └── index.ts           # Exports
├── types.ts               # Type definitions
├── logger.ts              # Logging utilities
└── index.ts               # Entry point

1. Create a new tool module in src/tools/ :

import { z } from "zod";
import type { ToolModule, ToolContext } from "./index.js";

const MyToolSchema = z.object({
  param: z.string().describe("Description of parameter"),
});

async function myTool(
  args: z.infer<typeof MyToolSchema>,
  context: ToolContext,
) {
  // Implementation
  return {
    content: [{ type: "text", text: "Result" }],
  };
}

export const myTools: ToolModule = {
  tools: [
    {
      name: "my_tool",
      description: "Description of what this tool does",
      inputSchema: MyToolSchema,
      handler: myTool,
    },
  ],
};

1. Register the module in src/server.ts :

import { myTools } from "./tools/my-tools.js";

// In the constructor:
this.toolRegistry.registerModule(myTools);

Enable debug logging for development:

export LOG_LEVEL=0

LOG_LEVEL=0
MCP_SERVER_LOG_FILE=debug-{timestamp}.log

View logs in real-time:

tail -f logs/debug-*.log

docker-compose logs -f tailscale-mcp

Variable	Description	Required	Default
TAILSCALE_API_KEY	Tailscale API key	Yes*	-
TAILSCALE_TAILNET	Tailscale tailnet name	Yes*	-
TAILSCALE_API_BASE_URL	API base URL	No	https://api.tailscale.com
LOG_LEVEL	Logging level (0-3)	No	1 (INFO)
MCP_SERVER_LOG_FILE	Server log file path (supports {timestamp})	No	-

*Required for API-based operations. CLI operations work without API credentials.

• Device listing and filtering

• Device authorization management

• Route management per device

• Network status monitoring

• Connection management

• Peer connectivity testing

• ACL management

• Device tagging

• Network lock operations

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass: npm test
6. Commit your changes: git commit -m 'Add amazing feature'
7. Push to the branch: git push origin feature/amazing-feature
8. Open a Pull Request

• Use TypeScript for all new code
• Add Zod schemas for input validation
• Include tests for new tools
• Follow the existing modular architecture
• Update documentation for new features

MIT License - see LICENSE file for details.

• Issues - Bug reports and feature requests
• Discussions - Questions and community support
• MCP Documentation - Learn more about MCP

See CHANGELOG.md for version history and updates.

source & further reading

github.com — original article I asked my coding agent to cat a file in –/.ssh. It did Show HN: phpClaw – AI agent runtime for PHP with tools, memory and guards Show HN: An open-source app for IELTS preparation