{"id":30294289,"url":"https://github.com/r167/tailscale-mcp","last_synced_at":"2026-07-16T04:31:50.272Z","repository":{"id":310259009,"uuid":"1039249087","full_name":"R167/tailscale-mcp","owner":"R167","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-16T21:08:57.000Z","size":44,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-10-19T05:51:32.641Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/R167.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-16T19:51:24.000Z","updated_at":"2025-08-16T21:09:00.000Z","dependencies_parsed_at":"2025-08-16T22:16:57.341Z","dependency_job_id":null,"html_url":"https://github.com/R167/tailscale-mcp","commit_stats":null,"previous_names":["r167/tailscale-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/R167/tailscale-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/R167%2Ftailscale-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/R167%2Ftailscale-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/R167%2Ftailscale-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/R167%2Ftailscale-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/R167","download_url":"https://codeload.github.com/R167/tailscale-mcp/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/R167%2Ftailscale-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35531123,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-16T02:00:06.687Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-17T01:21:22.681Z","updated_at":"2026-07-16T04:31:50.253Z","avatar_url":"https://github.com/R167.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tailscale MCP Server\n\nA Model Context Protocol (MCP) server that provides tools for interacting with Tailscale networks through the Tailscale API.\n\n## Design\n\n### Overview\n\nThis MCP server enables AI assistants to interact with Tailscale networks by providing a set of tools that wrap the Tailscale HTTP API. The server is built using:\n\n- **Tailscale Go Client v2**: Uses `tailscale.com/client/tailscale/v2` for comprehensive API interactions\n- **MCP Go SDK**: Uses `github.com/modelcontextprotocol/go-sdk` for MCP protocol implementation\n- **Streamable HTTP Transport**: Uses HTTP with streaming for robust communication with MCP clients\n- **OAuth2 Support**: Supports both API key and OAuth client credentials authentication\n\n### Architecture\n\n```\nAI Assistant \u003c-\u003e MCP Client \u003c-\u003e HTTP \u003c-\u003e Tailscale MCP Server \u003c-\u003e Tailscale API\n```\n\nThe server follows these key design principles:\n\n1. **Idiomatic Go**: Uses standard Go patterns and error handling\n2. **Security-First**: Requires explicit environment variable configuration for credentials\n3. **Minimal Dependencies**: Only essential packages for Tailscale API and MCP protocol\n4. **Tool-Based Architecture**: Each Tailscale operation is exposed as a separate MCP tool\n\n### Available Tools\n\nThe server provides the following tools:\n\n#### `list_devices`\n- **Description**: List all devices in the Tailscale network with full details\n- **Input**: No parameters required\n- **Output**: JSON array of comprehensive device information including names, IPs, status, routes, and metadata\n\n#### `get_device_details`\n- **Description**: Get detailed information about a specific device\n- **Input**: `deviceID` (string) - The device ID to get details for\n- **Output**: JSON object with full device information including routing, tags, and connectivity status\n\n#### `get_device_routes`\n- **Description**: Get subnet routes for a specific device\n- **Input**: `deviceID` (string) - The device ID to get routes for\n- **Output**: JSON object with advertised and enabled subnet routes for the device\n\n#### `get_acl`\n- **Description**: Get the current Access Control List (ACL) policy file for the tailnet\n- **Input**: No parameters required  \n- **Output**: JSON representation of the current ACL configuration\n\n#### `list_keys`\n- **Description**: List all API keys for the tailnet (both user and tailnet level)\n- **Input**: No parameters required\n- **Output**: JSON array of API key information including capabilities and expiration\n\n### Error Handling\n\nThe server implements robust error handling:\n\n- **API Errors**: Tailscale API errors are captured and returned as tool errors with descriptive messages\n- **JSON Marshaling Errors**: Any issues serializing responses are handled gracefully\n- **Authentication Errors**: Missing or invalid credentials result in clear error messages\n\n## Configuration\n\nThe server requires these environment variables:\n\n**Required:**\n- `TAILSCALE_TAILNET`: Your tailnet identifier (e.g., `example.com` or `user@domain.com`)\n\n**Authentication (choose one):**\n- `TAILSCALE_API_KEY`: Your Tailscale API key (obtain from Tailscale Admin Console)\n- OR `TAILSCALE_CLIENT_ID` + `TAILSCALE_CLIENT_SECRET`: OAuth client credentials\n\n**Optional:**\n- `PORT`: HTTP server port (defaults to 8080)\n\n## Usage\n\n### Building\n\n```bash\ngo build -o tailscale-mcp\n```\n\n### Running\n\n**Using API Key:**\n```bash\nexport TAILSCALE_API_KEY=\"your-api-key-here\"\nexport TAILSCALE_TAILNET=\"your-tailnet-here\"\nexport PORT=\"8080\"  # optional, defaults to 8080\n./tailscale-mcp\n```\n\n**Using OAuth Client Credentials:**\n```bash\nexport TAILSCALE_CLIENT_ID=\"your-client-id\"\nexport TAILSCALE_CLIENT_SECRET=\"your-client-secret\"\nexport TAILSCALE_TAILNET=\"your-tailnet-here\"\nexport PORT=\"8080\"  # optional, defaults to 8080\n./tailscale-mcp\n```\n\nThe server will start listening on the specified port (default 8080) and provide logs indicating when it's ready.\n\n### Integration with MCP Clients\n\nThe server uses streamable HTTP transport as per the MCP specification. Example configuration for Claude Desktop:\n\n**Using API Key:**\n```json\n{\n  \"mcpServers\": {\n    \"tailscale\": {\n      \"url\": \"http://localhost:8080\",\n      \"env\": {\n        \"TAILSCALE_API_KEY\": \"your-api-key\",\n        \"TAILSCALE_TAILNET\": \"your-tailnet\"\n      }\n    }\n  }\n}\n```\n\n**Using OAuth Client Credentials:**\n```json\n{\n  \"mcpServers\": {\n    \"tailscale\": {\n      \"url\": \"http://localhost:8080\",\n      \"env\": {\n        \"TAILSCALE_CLIENT_ID\": \"your-client-id\",\n        \"TAILSCALE_CLIENT_SECRET\": \"your-client-secret\",\n        \"TAILSCALE_TAILNET\": \"your-tailnet\"\n      }\n    }\n  }\n}\n```\n\nFor production deployments, configure with HTTPS and proper authentication.\n\n## Development\n\n### Dependencies\n\n- Go 1.25+\n- Tailscale account with API access\n- Valid Tailscale API key OR OAuth client credentials\n\n### Project Structure\n\nThe project is organized into modular packages:\n\n- `main.go`: Entry point\n- `config/`: Configuration and client initialization\n- `server/`: HTTP server setup and lifecycle management\n- `tools/`: MCP tool implementations organized by functionality\n  - `devices.go`: Device management tools\n  - `acl.go`: Access control list tools\n  - `keys.go`: API key management tools\n\n### Testing\n\nTo test the server functionality:\n\n1. **Local Testing**: Run the server with proper environment variables and test the HTTP endpoints\n2. **MCP Client Integration**: Integrate with an MCP client for end-to-end testing\n3. **Health Check**: The server will log startup status and any errors\n\n```bash\n# Test server startup (API Key)\nexport TAILSCALE_API_KEY=\"your-key\"\nexport TAILSCALE_TAILNET=\"your-tailnet\"\n./tailscale-mcp\n\n# OR test with OAuth credentials\nexport TAILSCALE_CLIENT_ID=\"your-client-id\"\nexport TAILSCALE_CLIENT_SECRET=\"your-client-secret\"\nexport TAILSCALE_TAILNET=\"your-tailnet\"\n./tailscale-mcp\n\n# In another terminal, you can test basic connectivity\ncurl -X POST http://localhost:8080 -H \"Content-Type: application/json\"\n```\n\n### OAuth Client Setup\n\nTo use OAuth client credentials instead of API keys:\n\n1. Go to the Tailscale Admin Console\n2. Navigate to Settings \u003e OAuth Clients\n3. Create a new OAuth client with appropriate scopes:\n   - `devices` - for device listing and management\n   - `routes` - for subnet route information\n   - `dns` - for DNS configuration access\n4. Use the generated Client ID and Client Secret with the server\n\n### Future Enhancements\n\nPotential additions to the server:\n\n- Device management operations (enable/disable, rename, set routes)\n- ACL modification capabilities  \n- DNS configuration management\n- User and group management\n- Audit log access\n- Real-time status monitoring\n- Webhook support for notifications\n\n## Security Considerations\n\n- All credentials (API keys, OAuth secrets) are handled securely through environment variables\n- No credentials are logged or exposed in error messages\n- OAuth client credentials provide more granular access control than API keys\n- All API operations respect Tailscale's built-in permissions and access controls\n- The server provides both read-only and read-write operations based on the configured scopes\n- OAuth tokens are automatically managed and refreshed by the client library\n\n## License\n\nThis project follows standard Go module practices and is designed for integration with Tailscale's official Go client library.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr167%2Ftailscale-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fr167%2Ftailscale-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr167%2Ftailscale-mcp/lists"}