{"slug": "tailscale-mcp-connect-tailscale-with-claude", "title": "Tailscale MCP: Connect Tailscale with Claude", "summary": "A developer publishing as HexSleeves released a Model Context Protocol server, @hexsleeves/tailscale-mcp-server, that connects Claude to Tailscale's CLI and REST API for automated network management. The server is distributed via npm, Docker Hub (hexsleeves/tailscale-mcp-server) and the GitHub Container Registry (ghcr.io/hexsleeves/tailscale-mcp-server), and exposes tools including list_devices, device_action, manage_routes, get_network_status, connect_network, disconnect_network, ping_peer, get_version and get_tailnet_info. It is configured in Claude Desktop through ~/.claude/claude_desktop_config.json with TAILSCALE_API_KEY and TAILSCALE_TAILNET environment variables.", "body_md": "A modern [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that provides seamless integration with Tailscale's CLI commands and REST API, enabling automated network management and monitoring through a standardized interface.\n\n- **NPM** :[`@hexsleeves/tailscale-mcp-server`](https://www.npmjs.com/package/@hexsleeves/tailscale-mcp-server)\n- **Docker Hub** :[`hexsleeves/tailscale-mcp-server`](https://hub.docker.com/r/hexsleeves/tailscale-mcp-server)\n- **GitHub Container Registry** :[`ghcr.io/hexsleeves/tailscale-mcp-server`](https://github.com/users/HexSleeves/packages/container/package/tailscale-mcp-server)\n\n- **Device Management** : List, authorize, deauthorize, and manage Tailscale devices\n- **Network Operations** : Connect/disconnect, manage routes, and monitor network status\n- **Security Controls** : Manage ACLs, device tags, and network lock settings\n- **Modern Architecture** : Modular tool system with TypeScript and Zod validation\n- **CLI Integration** : Direct integration with Tailscale CLI commands\n- **API Integration** : REST API support for advanced operations\n\nRun directly without installation:\n\n```\n# Method 1: Explicit package syntax (most reliable)\nnpx --package=@hexsleeves/tailscale-mcp-server tailscale-mcp-server\n\n# Method 2: Direct syntax (may work depending on npx version)\nnpx -y @hexsleeves/tailscale-mcp-server\n```\n\n**Note**: Method 1 with `--package=` syntax is more reliable across different npx versions and environments.\n\nOr install globally:\n\n```\nnpm install -g @hexsleeves/tailscale-mcp-server\ntailscale-mcp-server\n# Pull and run from Docker Hub\ndocker run -d \\\n  --name tailscale-mcp \\\n  -e TAILSCALE_API_KEY=your_api_key \\\n  -e TAILSCALE_TAILNET=your_tailnet \\\n  hexsleeves/tailscale-mcp-server:latest\n# Pull and run from GitHub Container Registry\ndocker run -d \\\n  --name tailscale-mcp \\\n  -e TAILSCALE_API_KEY=your_api_key \\\n  -e TAILSCALE_TAILNET=your_tailnet \\\n  ghcr.io/hexsleeves/tailscale-mcp-server:latest\n# Use the included docker-compose.yml\ndocker-compose up -d\n```\n\nAdd to your Claude Desktop configuration (`~/.claude/claude_desktop_config.json`):\n\n```\n{\n  \"mcpServers\": {\n    \"tailscale\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"--package=@hexsleeves/tailscale-mcp-server\",\n        \"tailscale-mcp-server\"\n      ],\n      \"env\": {\n        \"TAILSCALE_API_KEY\": \"your-api-key-here\",\n        \"TAILSCALE_TAILNET\": \"your-tailnet-name\"\n      }\n    }\n  }\n}\n{\n  \"mcpServers\": {\n    \"tailscale\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"--rm\",\n        \"-i\",\n        \"-e\",\n        \"TAILSCALE_API_KEY=xxxxxxxxxxxxx\",\n        \"-e\",\n        \"TAILSCALE_TAILNET=your-tailnet\",\n        \"hexsleeves/tailscale-mcp-server:latest\"\n      ]\n    }\n  }\n}\n{\n  \"mcpServers\": {\n    \"tailscale-docker\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"--rm\",\n        \"-i\",\n        \"-e\",\n        \"TAILSCALE_API_KEY=xxxxxxxxxxxxx\",\n        \"-e\",\n        \"TAILSCALE_TAILNET=your-tailnet\",\n        \"ghcr.io/hexsleeves/tailscale-mcp-server:latest\"\n      ]\n    }\n  }\n}\n# Required for API operations\nexport TAILSCALE_API_KEY=\"your-api-key\"\nexport TAILSCALE_TAILNET=\"your-tailnet\"\n\n# Optional: Custom API base URL\nexport TAILSCALE_API_BASE_URL=\"https://api.tailscale.com\"\n\n# Optional: Logging configuration\nexport LOG_LEVEL=\"1\"  # 0=DEBUG, 1=INFO, 2=WARN, 3=ERROR\nexport MCP_SERVER_LOG_FILE=\"tailscale-mcp-{timestamp}.log\"  # Enable file logging\n```\n\n- `list_devices` - List all devices in the Tailscale network\n- `device_action` - Perform actions on specific devices (authorize, deauthorize, delete, expire-key)\n- `manage_routes` - Enable or disable routes for devices\n\n- `get_network_status` - Get current network status from Tailscale CLI\n- `connect_network` - Connect to the Tailscale network\n- `disconnect_network` - Disconnect from the Tailscale network\n- `ping_peer` - Ping a peer device\n\n- `get_version` - Get Tailscale version information\n- `get_tailnet_info` - Get detailed network information\n\nFor local development and testing, clone the repository and set up the development environment:\n\n```\n# Clone the repository\ngit clone https://github.com/HexSleeves/tailscale-mcp-server.git\ncd tailscale-mcp-server\n\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n# Copy the example environment file\ncp .env.example .env\n\n# Create logs directory\nmkdir -p logs\n\n# Edit .env with your actual Tailscale credentials\n# TAILSCALE_API_KEY=your-actual-api-key\n# TAILSCALE_TAILNET=your-actual-tailnet\n```\n\nThe `.env.example` file contains all available configuration options with documentation. Key variables for testing:\n\n- **TAILSCALE_API_KEY** : Get from[Tailscale Admin Console](https://login.tailscale.com/admin/settings/keys)\n- **TAILSCALE_TAILNET** : Your organization/tailnet name\n- **LOG_LEVEL** : Set to`0` for debug logging during development\n- **MCP_SERVER_LOG_FILE** : Enable server logging to file\n- **MCP_LOG_FILE** : Enable test script logging to file\n\nFor development, configure Claude Desktop to use your local build:\n\n```\n{\n  \"mcpServers\": {\n    \"tailscale-dev\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/your/tailscale-mcp-server/dist/index.js\"],\n      \"env\": {\n        \"TAILSCALE_API_KEY\": \"your-api-key-here\",\n        \"TAILSCALE_TAILNET\": \"your-tailnet-name\",\n        \"LOG_LEVEL\": \"0\"\n      }\n    }\n  }\n}\n{\n  \"mcpServers\": {\n    \"tailscale-dev\": {\n      \"command\": \"npm\",\n      \"args\": [\"run\", \"start\"],\n      \"cwd\": \"/path/to/your/tailscale-mcp-server\",\n      \"env\": {\n        \"TAILSCALE_API_KEY\": \"your-api-key-here\",\n        \"TAILSCALE_TAILNET\": \"your-tailnet-name\",\n        \"LOG_LEVEL\": \"0\"\n      }\n    }\n  }\n}\n# Build for development\nnpm run build:dev\n\n# Build and watch for changes\nnpm run build:watch\n\n# Run in development mode with auto-restart\nnpm run dev\n\n# Run tests\nnpm test\n\n# Run tests in watch mode\nnpm run test:watch\n\n# Run tests with coverage\nnpm run test:coverage\n\n# Test with MCP Inspector\nnpm run inspector\n\n# Lint code\nnpm run lint\n\n# Format code\nnpm run format\n```\n\nThe project includes an interactive publishing script that handles version bumping and publishing to multiple registries:\n\n```\n# Run the interactive publish script\nnpm run publish\n\n# Or run directly\n./scripts/publish.sh\n```\n\nThe script will guide you through:\n\n1. **Version Bumping** : Choose between patch, minor, major, or skip\n2. **NPM Publishing** : Optionally publish to npm registry\n3. **Docker Hub** : Optionally build and publish Docker images\n4. **GitHub Container Registry** : Optionally publish to GHCR\n5. **Git Operations** : Automatically commit version changes and create tags\n\n- **Interactive prompts** for each publishing step\n- **Automatic version bumping** with semantic versioning\n- **Git integration** with automatic tagging and commits\n- **Multi-registry support** (npm, Docker Hub, GHCR)\n- **Safety checks** for uncommitted changes\n- **Colored output** for better visibility\n- **Error handling** with proper exit codes\n- **Performance optimized** with pre-calculated version previews\n\n- **NPM** : Logged in with`npm login` and proper access to the package\n- **Docker Hub** : Logged in with`docker login`\n- **GHCR** : Logged in with`docker login ghcr.io` using a GitHub token\n- **Git** : Clean working directory (or confirmation to proceed with uncommitted changes)\n\nFor Docker-based development:\n\n```\n# Build development image\ndocker build -t tailscale-mcp-dev .\n\n# Run with development environment\ndocker run -it --rm \\\n  -v $(pwd):/app \\\n  -v /app/node_modules \\\n  -e TAILSCALE_API_KEY=your_api_key \\\n  -e TAILSCALE_TAILNET=your_tailnet \\\n  -e LOG_LEVEL=0 \\\n  tailscale-mcp-dev\n\n# Or use Docker Compose for development\ndocker-compose -f docker-compose.dev.yml up\nsrc/\n├── server.ts              # Main server implementation\n├── tools/                 # Modular tool definitions\n│   ├── index.ts           # Tool registry system\n│   ├── device-tools.ts    # Device management tools\n│   └── ...                # Additional tool modules\n├── tailscale/             # Tailscale integrations\n│   ├── tailscale-api.ts   # REST API client\n│   ├── tailscale-cli.ts   # CLI wrapper\n│   └── index.ts           # Exports\n├── types.ts               # Type definitions\n├── logger.ts              # Logging utilities\n└── index.ts               # Entry point\n```\n\n1. Create a new tool module in `src/tools/` :\n\n``` python\nimport { z } from \"zod\";\nimport type { ToolModule, ToolContext } from \"./index.js\";\n\nconst MyToolSchema = z.object({\n  param: z.string().describe(\"Description of parameter\"),\n});\n\nasync function myTool(\n  args: z.infer<typeof MyToolSchema>,\n  context: ToolContext,\n) {\n  // Implementation\n  return {\n    content: [{ type: \"text\", text: \"Result\" }],\n  };\n}\n\nexport const myTools: ToolModule = {\n  tools: [\n    {\n      name: \"my_tool\",\n      description: \"Description of what this tool does\",\n      inputSchema: MyToolSchema,\n      handler: myTool,\n    },\n  ],\n};\n```\n\n1. Register the module in `src/server.ts` :\n\n``` js\nimport { myTools } from \"./tools/my-tools.js\";\n\n// In the constructor:\nthis.toolRegistry.registerModule(myTools);\n```\n\nEnable debug logging for development:\n\n```\n# Set environment variable\nexport LOG_LEVEL=0\n\n# Or in .env file\nLOG_LEVEL=0\nMCP_SERVER_LOG_FILE=debug-{timestamp}.log\n```\n\nView logs in real-time:\n\n```\n# Follow server logs\ntail -f logs/debug-*.log\n\n# Or use Docker logs\ndocker-compose logs -f tailscale-mcp\n```\n\n| Variable | Description | Required | Default | \n|---|---|---|---|\n| `TAILSCALE_API_KEY` | Tailscale API key | Yes* | - | \n| `TAILSCALE_TAILNET` | Tailscale tailnet name | Yes* | - | \n| `TAILSCALE_API_BASE_URL` | API base URL | No | `https://api.tailscale.com` | \n| `LOG_LEVEL` | Logging level (0-3) | No | `1` (INFO) | \n| `MCP_SERVER_LOG_FILE` | Server log file path (supports {timestamp}) | No | - | \n\n*Required for API-based operations. CLI operations work without API credentials.\n\n- Device listing and filtering\n- Device authorization management\n- Route management per device\n\n- Network status monitoring\n- Connection management\n- Peer connectivity testing\n\n- ACL management\n- Device tagging\n- Network lock operations\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Make your changes\n4. Add tests for new functionality\n5. Ensure all tests pass: `npm test`\n6. Commit your changes: `git commit -m 'Add amazing feature'`\n7. Push to the branch: `git push origin feature/amazing-feature`\n8. Open a Pull Request\n\n- Use TypeScript for all new code\n- Add Zod schemas for input validation\n- Include tests for new tools\n- Follow the existing modular architecture\n- Update documentation for new features\n\nMIT License - see [LICENSE](https://github.com/HexSleeves/tailscale-mcp/blob/main/.github/LICENSE) file for details.\n\n- [Issues](https://github.com/your-repo/issues) - Bug reports and feature requests\n- [Discussions](https://github.com/your-repo/discussions) - Questions and community support\n- [MCP Documentation](https://modelcontextprotocol.io) - Learn more about MCP\n\nSee [CHANGELOG.md](https://github.com/HexSleeves/tailscale-mcp/blob/main/.github/CHANGELOG.md) for version history and updates.", "url": "https://wpnews.pro/news/tailscale-mcp-connect-tailscale-with-claude", "canonical_source": "https://github.com/HexSleeves/tailscale-mcp", "published_at": "2026-10-29 20:22:24+00:00", "updated_at": "2026-10-29 20:47:14.297433+00:00", "lang": "en", "topics": ["ai-agents", "agent-protocols", "developer-tools", "ai-tools"], "entities": ["Tailscale", "Claude", "Anthropic", "Model Context Protocol", "HexSleeves", "@hexsleeves/tailscale-mcp-server", "Docker Hub", "GitHub Container Registry"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/tailscale-mcp-connect-tailscale-with-claude", "markdown": "https://wpnews.pro/news/tailscale-mcp-connect-tailscale-with-claude.md", "text": "https://wpnews.pro/news/tailscale-mcp-connect-tailscale-with-claude.txt", "jsonld": "https://wpnews.pro/news/tailscale-mcp-connect-tailscale-with-claude.jsonld"}}