What is Tailscale Mcp

Tailscale MCP is a Model Context Protocol server designed for Tailscale, allowing users to perform detailed queries about devices within their tailnet using compatible LLM clients like Claude Desktop.

Use cases

Use cases for Tailscale MCP include querying device details for troubleshooting, integrating device information into AI-driven applications, and managing network devices efficiently within a Tailscale environment.

How to use

To use Tailscale MCP, you need a Tailscale account with an Admin API key. Download the pre-built binaries for your platform from the GitHub releases page and follow the installation instructions. You can also build from source if preferred.

Key features

Key features of Tailscale MCP include support for MCP interactions over Server-Sent Events (SSE) and stdio, detailed device information queries by ID, hostname, or IP address, listing all devices within your Tailscale network, and OAuth Grants middleware integration with Tailscale.

Where to use

Tailscale MCP can be used in various fields such as network management, device monitoring, and integration with AI applications that require device context information.

Tailscale MCP Server

An MCP (Model Context Protocol) server for Tailscale, enabling detailed queries about devices, policy files, and tailnet settings via Claude Desktop or other compatible LLM clients. Features comprehensive Tailscale OAuth grants integration for fine-grained access control.

Features

• Multiple Server Modes: Supports both stdio and HTTP (with SSE) modes
• Comprehensive Tailscale Integration: Query devices, policy files, and tailnet settings
• OAuth Grants Authorization: Fine-grained access control using Tailscale grants with custom MCP capabilities
• Dual Network Access: Accessible via both Tailscale network and localhost
• Claude Desktop Compatible: Optimized for Claude Desktop integration
• Flexible Logging: TTY-aware logging with configurable debug levels

Prerequisites

• Tailscale account with an Admin API key
• Go 1.22 or higher (if building from source)

Installation

Download Pre-Built Binaries

Grab the latest pre-built binary for your platform from the release page.

macOS

1. Download the latest release archive for macOS (ts-mcp-<version>-darwin-amd64.tar.gz or ts-mcp-<version>-darwin-arm64.tar.gz)
2. Extract and install:

tar -xzf ts-mcp-<version>-darwin-*.tar.gz
sudo mv ts-mcp /usr/local/bin/

You can also install with homebrew:

brew install jaxxstorm/tap/ts-mcp

Linux

1. Download the latest release archive for Linux (ts-mcp-<version>-linux-amd64.tar.gz or ts-mcp-<version>-linux-arm64.tar.gz)
2. Extract and install:

tar -xzf ts-mcp-<version>-linux-*.tar.gz
sudo mv ts-mcp /usr/local/bin/

Windows

1. Download the latest release ZIP archive for Windows (ts-mcp-<version>-windows-amd64.zip or ts-mcp-<version>-windows-arm64.zip)
2. Extract the binary (ts-mcp.exe) and move it to a preferred location, such as C:\Program Files\ts-mcp\
3. Add the chosen location to your system’s PATH if desired

Building From Source

If you prefer building the binary from source:

1. Clone the Repository

git clone <repo_url>
cd <repo_dir>

2. Install Dependencies

go mod tidy

3. Build the Binary

go build -o ts-mcp main.go

Configuration

Required Environment Variables

export TAILSCALE_API_KEY="tskey-yourapikey"
export TAILSCALE_TAILNET="yourtailnet.com"

Optional Environment Variables

export TS_HOSTNAME="ts-mcp"          # Tailscale hostname (default: ts-mcp)
export TS_PORT="8080"                # Port to listen on (default: 8080)
export TS_AUTH_KEY=""                # Tailscale auth key for automatic authentication

Command Line Options

• --debug / -d: Enable debug logging
• --version / -v: Show version information
• --stdio: Use stdio mode instead of HTTP (required for Claude Desktop)

Getting Your API Key

1. Go to Tailscale Admin Console
2. Generate an API key with the following permissions:
   • Read devices
   • Read policy file
   • Read tailnet settings

OAuth Grants & Access Control

This server implements fine-grained access control using Tailscale OAuth grants. You can configure custom MCP capabilities in your Tailscale ACL policy file to control which users can access specific tools and resources.

ACL Configuration Example

Add the following to your Tailscale ACL policy file:

{
  "grants": [
    {
      "src": [
        "user:[email protected]"
      ],
      "dst": [
        "tag:mcp-server"
      ],
      "app": {
        "jaxxstorm.com/cap/mcp": [
          {
            "tools": [
              "*"
            ],
            "resources": [
              "*"
            ]
          }
        ]
      }
    },
    {
      "src": [
        "user:[email protected]"
      ],
      "dst": [
        "tag:mcp-server"
      ],
      "app": {
        "jaxxstorm.com/cap/mcp": [
          {
            "tools": [
              "list_all_devices"
            ],
            "resources": [
              "bootstrap://status",
              "tailscale://devices"
            ]
          }
        ]
      }
    }
  ]
}

Grant Permissions

Tools: Control which MCP tools users can execute

• get_device_info: Allow querying specific device details
• list_all_devices: Allow listing all devices
• *: Allow all tools

Resources: Control which MCP resources users can access

• bootstrap://status: Health check endpoint
• tailscale://devices: Device list resource
• tailscale://policy: Policy file access
• tailscale://tailnet-settings: Tailnet settings access
• tailscale://device: Individual device resource access
• *: Allow all resources

Running the Server

HTTP Mode (Default)

./ts-mcp

The server will be accessible via:

• Tailscale network: http://<hostname>.yourtailnet.ts.net:8080/mcp
• Localhost: http://127.0.0.1:8080/mcp

Stdio Mode (Required for Claude Desktop)

./ts-mcp --stdio

Claude Desktop Integration

Claude Desktop currently supports stdio mode for MCP servers.

Configuration Steps

1. Locate your Claude Desktop MCP config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Edit claude_desktop_config.json:

{
  "mcpServers": {
    "tailscale": {
      "command": "/usr/local/bin/ts-mcp",
      "args": [
        "--stdio"
      ],
      "env": {
        "TAILSCALE_API_KEY": "tskey-yourapikey",
        "TAILSCALE_TAILNET": "yourtailnet.com"
      }
    }
  }
}

3. Restart Claude Desktop

Claude will now recognize your MCP server and you can interact with your Tailscale network.

Available Tools & Resources

Tools (Recommended for Claude)

Tool	Description	Arguments	Required Grant
get_device_info	Fetch device details by ID, IP, or hostname	device: Device identifier	get_device_info
list_all_devices	List all devices in your tailnet	None	list_all_devices

Resources

URI	Description	Required Grant
bootstrap://status	Health-check endpoint	bootstrap://status
tailscale://devices	Complete device list with metadata	tailscale://devices
tailscale://policy	Current Tailscale ACL policy file	tailscale://policy
tailscale://tailnet-settings	Tailnet configuration and settings	tailscale://tailnet-settings
tailscale://device	Individual device details (parameterized)	tailscale://device

Note: Tools are preferred for Claude Desktop as they provide better compatibility and error handling.

Example Claude Desktop Queries

Get Device Information

Use get_device_info to get details about device "100.101.102.103"

List All Devices

List all devices in my tailnet using list_all_devices

Check Tailnet Policy

Show me the current Tailscale policy by reading the tailscale://policy resource

Monitor Device Status

Get the status of my work laptop and show me when it was last seen

Security Features

• Tailscale OAuth Integration: Leverages Tailscale’s built-in authentication
• Fine-grained Access Control: Granular permissions via MCP capabilities in ACL grants
• Network Isolation: All communication flows through your private Tailscale network
• User Context Logging: Comprehensive audit trail of user actions
• Origin Validation: HTTP mode includes origin validation for additional security

Logging

The server provides comprehensive logging with multiple levels:

• Default: Info level with key operations
• Debug (-d): Detailed protocol-level debugging including OAuth grants inspection

Log output automatically adapts:

• TTY: Colorized, human-readable format with timestamps
• Non-TTY: Structured JSON for log aggregation systems

Troubleshooting

Common Issues

“No MCP capabilities found”

• Verify your ACL policy includes the correct grants configuration
• Check that the server node has the appropriate tags
• Ensure the user has been granted access to MCP capabilities

“Access denied: insufficient permissions”

• Review the grants configuration in your ACL policy
• Verify the user is listed in the src field of the relevant grant
• Check that the requested tool/resource is included in the capability definition

“Failed to get Tailscale status”

• Ensure Tailscale is running and authenticated
• Verify the API key has the required permissions
• Check network connectivity to Tailscale coordination servers

Debug Mode

Enable debug logging to see detailed protocol exchanges and OAuth grants:

./ts-mcp --debug --stdio

This will show:

• Detailed MCP message flow
• OAuth grants parsing and validation
• User authentication context
• Access control decisions

Dependencies

• github.com/alecthomas/kong - CLI parsing
• github.com/mark3labs/mcp-go - MCP protocol implementation
• github.com/tailscale/hujson - HuJSON parsing for policy files
• go.uber.org/zap - Structured logging
• golang.org/x/term - TTY detection
• tailscale.com/client/tailscale/v2 - Tailscale API client
• tailscale.com/tsnet - Tailscale network integration

Version

Current version: 0.0.2

Use ./ts-mcp --version to check your installed version.

License

[Add your license information here]

Contributing

[Add contribution guidelines here]

Useful Links

• Tailscale API Documentation
• Tailscale OAuth Grants
• Claude Desktop
• MCP Protocol Documentation