Skip to main content
Glama

CI Claude Code License

English | 繁體中文 | 简体中文

$ tailscale_validate_policy { "path": "/repo/policy.hujson" }
{"data": {"valid": false, "message": "test(s) failed", "failures": [
  {"user": "x@example.com", "errors": ["address \"100.64.0.1:22\": want: Accept, got: Drop"]}]}}

An agent that needs to know which machines are online, or whether a policy change is safe, should not drive the admin console in a browser. This plugin gives Codex and Claude Code 5 read-only tools that call the Tailscale API directly.

Features

  • Lists devices: names, addresses, owners, tags, online state, key expiry and subnet routes, with filters.

  • Finds one device: by node ID, MagicDNS name, hostname or tailnet address.

  • Reads the live policy: the policy file as HuJSON with its ETag, to compare with the copy in your repository.

  • Validates a policy before it ships: Tailscale parses a candidate file and runs its tests, and nothing changes.

  • Explains its own access: one tool reports the credential source and the OAuth scopes it was granted.

Related MCP server: tailscale-rmcp

Quick start

claude plugin marketplace add zyx1121/marketplace
claude plugin install tailscale@zyx1121

Codex: codex plugin marketplace add zyx1121/marketplace, then codex plugin add tailscale@zyx1121.

The plugin needs Bun and one credential. Create an OAuth client in the Tailscale admin console with the scopes devices:core:read and policy_file:read, then export it:

export TAILSCALE_OAUTH_CLIENT_ID=...
export TAILSCALE_OAUTH_CLIENT_SECRET=...

Open a new session and ask "Which of my devices are offline?".

Usage

Tool

Does

tailscale_list_devices

lists devices, filtered by query, tag or online

tailscale_get_device

returns every field of one device

tailscale_get_policy

returns the live policy file and its ETag

tailscale_validate_policy

checks a policy given as policy text or as a file path

tailscale_get_capabilities

reports the credential source, granted scopes and tools

  • Every result is an envelope: data on success, or error with a code and a hint.

  • A permission_denied error names the scopes that the credential has. Add the missing scope in the admin console.

  • The plugin never changes the tailnet. Apply a policy from the repository that owns it.

Configuration

Variable

Sets

Default

TAILSCALE_API_KEY

an API access token, used first when set

none

TAILSCALE_OAUTH_CLIENT_ID

the OAuth client ID

none

TAILSCALE_OAUTH_CLIENT_SECRET

the OAuth client secret

none

TAILSCALE_KEYCHAIN_SERVICE

macOS keychain item that holds the OAuth client

none

TAILSCALE_TAILNET

the tailnet to read

- (the credential's own tailnet)

With TAILSCALE_KEYCHAIN_SERVICE, the item is a generic password. Its account is the client ID and its password is the client secret, so the secret stays out of the environment:

security add-generic-password -s tailscale-mcp -a <client-id> -w
export TAILSCALE_KEYCHAIN_SERVICE=tailscale-mcp

How it works

The Bun MCP server calls https://api.tailscale.com/api/v2 with fetch. For an OAuth client it requests an access token, keeps it in memory until one minute before it expires, and requests a new one after a 401. Policy validation posts the candidate file to the acl/validate endpoint, which runs the tests inside the file and stores nothing.

Limits

  • Read-only. It does not authorize, tag, rename or remove devices, and it does not write the policy file.

  • tailscale_get_device needs a selector that matches exactly one device. Two devices can share a hostname.

  • The keychain option works on macOS only.

For AI agents

Facts for coding agents and LLM tools. The rules for changing the code are in AGENTS.md.

  • Summary: Claude Code and Codex plugin with 5 read-only MCP tools for Tailscale devices and the tailnet policy file.

  • Type: plugin

  • Interfaces: MCP tailscale (stdio, dist/server.js)

  • Install: claude plugin install tailscale@zyx1121, after claude plugin marketplace add zyx1121/marketplace

  • Run: the host starts the MCP server

  • Verify: call tailscale_get_capabilities and read configured and scopes

  • Config: TAILSCALE_API_KEY, TAILSCALE_OAUTH_CLIENT_ID, TAILSCALE_OAUTH_CLIENT_SECRET, TAILSCALE_KEYCHAIN_SERVICE, TAILSCALE_TAILNET

  • Secrets: one Tailscale credential, from the environment or the macOS keychain. It never appears in a result.

  • Limits: read-only. No device or policy writes.

Development

bun install --frozen-lockfile
bun run check

The tests mock fetch and never call Tailscale. The marketplace pins each release commit.

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides read-only MCP tools for TaskMarket, enabling users to list open tasks, inspect task details, and prepare delegation drafts with approval fingerprints.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides read-only MCP tools that let an LLM client query network inventories, inspect devices over SSH, and diagnose network conditions such as interfaces, routes, BGP, OSPF, and VPN state. Configuration changes stay in the local CLI, while the MCP surface remains strictly read-only.
      Apache 2.0