{"id":27671539,"url":"https://github.com/aantti/mcp-netbird","last_synced_at":"2025-04-24T23:37:01.399Z","repository":{"id":284223306,"uuid":"954241063","full_name":"aantti/mcp-netbird","owner":"aantti","description":"MCP Server for Netbird","archived":false,"fork":false,"pushed_at":"2025-04-16T13:27:19.000Z","size":82,"stargazers_count":28,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-16T20:06:09.218Z","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":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aantti.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2025-03-24T19:21:55.000Z","updated_at":"2025-04-16T13:27:23.000Z","dependencies_parsed_at":"2025-03-24T20:25:55.018Z","dependency_job_id":"77b6676c-506f-4b9d-8cdf-6b4c6ca3fd71","html_url":"https://github.com/aantti/mcp-netbird","commit_stats":null,"previous_names":["aantti/mcp-netbird"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aantti%2Fmcp-netbird","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aantti%2Fmcp-netbird/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aantti%2Fmcp-netbird/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aantti%2Fmcp-netbird/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aantti","download_url":"https://codeload.github.com/aantti/mcp-netbird/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250729114,"owners_count":21477608,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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-04-24T23:37:00.070Z","updated_at":"2025-04-24T23:37:01.392Z","avatar_url":"https://github.com/aantti.png","language":"Go","funding_links":[],"categories":["Cloud \u0026 Infrastructure","Security","Cloud Services","⚙️ DevOps","Community Servers","カテゴリ","Other"],"sub_categories":["Cloud Platforms","How to Submit","☁️ \u003ca name=\"cloud--infrastructure\"\u003e\u003c/a\u003eクラウド・インフラ"],"readme":"# Netbird MCP Server\n\nA [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for [Netbird](https://netbird.io/).\n\nThis project is derived from the [MCP Server for Grafana](https://github.com/grafana/mcp-grafana) by Grafana Labs and is licensed under the same Apache License 2.0.\n\nIt also uses [MCP Go](https://github.com/mark3labs/mcp-go) by Mark III Labs.\n\n**Note: this project is still in development.**\n\n## Installing\n\n### Installing from source\n\n#### Clone the repository\n\n```bash\ngit clone https://github.com/aantti/mcp-netbird\n```\n\n#### Build and install\n\n```bash\ncd mcp-netbird \u0026\u0026 \\\nmake install\n```\n\n### Installing from GitHub\n\n```bash\ngo install github.com/aantti/mcp-netbird/cmd/mcp-netbird@latest\n```\n\n### Installing via Smithery\n\n[![smithery badge](https://smithery.ai/badge/@aantti/mcp-netbird)](https://smithery.ai/server/@aantti/mcp-netbird)\n\nTo install Netbird MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@aantti/mcp-netbird):\n\n```bash\nnpx -y @smithery/cli install @aantti/mcp-netbird --client claude\n```\n\n## Configuration\n\nThe server requires the following environment variables:\n\n- `NETBIRD_API_TOKEN`: Your Netbird API token\n- `NETBIRD_HOST` (optional): The Netbird API host (default is `api.netbird.io`)\n\n## Features\n\nThis server uses the Netbird API to provide LLMs information about Netbird network. Currently it's a 1:1 mapping of select read-only Netbird API resources to tools.\n\n- [x] Uses Netbird API to access configuration and status\n- [x] Configurable API endpoint\n- [x] Secure token-based authentication for Netbird API\n\n### Tools\n\n| Tool | Description | Netbird API |\n| --- | --- | --- |\n| `list_netbird_peers` | All peers | [List all Peers](https://docs.netbird.io/api/resources/peers#list-all-peers) |\n| `list_netbird_port_allocations` | All ingress ports for `peerId` | [List all Port Allocations](https://docs.netbird.io/api/resources/ingress-ports) |\n| `list_netbird_groups` | All groups | [List all Groups](https://docs.netbird.io/api/resources/groups#list-all-groups) |\n| `list_netbird_policies` | All policies | [List all Policies](https://docs.netbird.io/api/resources/policies#list-all-policies) |\n| `list_netbird_posture_checks` | All posture checks | [List all Posture Checks](https://docs.netbird.io/api/resources/posture-checks#list-all-posture-checks) |\n| `list_netbird_networks` | All networks | [List all Networks](https://docs.netbird.io/api/resources/networks#list-all-networks) |\n| `list_netbird_nameservers` | All nameserver groups | [List all Nameserver Groups](https://docs.netbird.io/api/resources/dns) |\n\n### Adding tools\n\nTo add new tools:\n\n1. Create a new file in `tools` (e.g., `tools/users.go`), possibly use existing code as a template\n2. Add API route and response specifics to the new file\n3. Add the tool to `func newServer()` in `cmd/main.go`\n\n## Usage\n\n1. Get your [Netbird API token](https://docs.netbird.io/api/guides/authentication) from the Netbird management console.\n\n2. Install the `mcp-netbird` binary using one of the installation methods above. Make sure the binary is in your PATH.\n\n3. Add the server configuration to your client configuration file. E.g., for Codeium Windsurf add the following to `~/.codeium/windsurf/mcp_config.json`:\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"netbird\": {\n         \"command\": \"mcp-netbird\",\n         \"args\": [],\n         \"env\": {\n           \"NETBIRD_API_TOKEN\": \"\u003cyour-api-token\u003e\"\n         }\n       }\n     }\n   }\n   ```\n\nFor more information on how to add a similar configuration to Claude Desktop, see [here](https://modelcontextprotocol.io/quickstart/user).\n\n\u003e Note: if you see something along the lines of `[netbird] [error] spawn mcp-netbird ENOENT` in Claude Desktop logs, you need to specify the full path to `mcp-netbird`. On macOS Claude Logs are in `~/Library/Logs/Claude`.\n\n4. Try asking questions along the lines of \"Can you explain my Netbird peers, groups and policies to me?\"\n   \n![claude-desktop-mcp-netbird](https://github.com/user-attachments/assets/094614cd-9399-4c90-adb3-06ae67c604e4)\n\n## Docker\n\nBuild an image and tag it:\n\n```bash\ndocker build -t mcp-netbird-sse:v1 -f Dockerfile.sse .\n```\n\nRun the image:\n\n```bash\ndocker run --name mcp-netbird -p 8001:8001 -e NETBIRD_API_TOKEN=\u003cyour-api-token\u003e mcp-netbird-sse:v1\n\n```\n\n## ToolHive\n\n[ToolHive](https://github.com/StacklokLabs/toolhive) (thv) is a lightweight utility designed to simplify the deployment and management of MCP servers.\n\nYou can use ToolHive to deploy and run Netbird MCP as follows:\n\n1. Install `thv` as described in [ToolHive README](https://github.com/StacklokLabs/toolhive#installation).\n\n2. Add Netbird API token to `thv` secrets:\n\n```bash\nthv secret set netbird\n```\n\n3. Build an SSE image as described in the Docker section [above](#docker)\n\n4. Start Netbird MCP with `thv run` on port 8080:\n\n```bash\nthv run --secret netbird,target=NETBIRD_API_TOKEN --transport sse --name thv-mcp-netbird --port 8080 --target-port 8001 mcp-netbird-sse:v1\n```\n\n5. When you want to stop the server, use:\n\n```bash\nthv stop thv-mcp-netbird\n```\n\n## Development\n\nContributions are welcome! Please open an issue or submit a pull request if you have any suggestions or improvements.\n\nThis project is written in Go. Install Go following the instructions for your platform.\n\nTo run the server manually, use:\n\n```bash\nexport NETBIRD_API_TOKEN=your-token \u0026\u0026 \\\ngo run cmd/mcp-netbird/main.go\n```\n\nOr in SSE mode:\n\n```bash\nexport NETBIRD_API_TOKEN=your-token \u0026\u0026 \\\ngo run cmd/mcp-netbird/main.go --transport sse --sse-address :8001\n```\n\n### Debugging\n\nThe **MCP Inspector** is an interactive developer tool for testing and debugging MCP servers. Read more about it [here](https://modelcontextprotocol.io/docs/tools/inspector).\n\nHere's how to start the MCP Inspector:\n\n```bash\nexport NETBIRD_API_TOKEN=your-token \u0026\u0026 \\\nnpx @modelcontextprotocol/inspector\n```\n\nNetbird MCP Server can then be tested with either `stdio` or `SSE` transport type. For `stdio` specify the full path to `mcp-netbird` in the UI.\n\n### Testing\n\n**TODO: add more tests**\n\n### Linting\n\nTo lint the code, run:\n\n```bash\nmake lint\n```\n\n## License\n\nThis project is licensed under the [Apache License, Version 2.0](LICENSE).\n\nThis project includes software developed at Grafana Labs (https://grafana.com/).\n\nThis project includes software developed at Mark III Labs (https://github.com/mark3labs/mcp-go).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faantti%2Fmcp-netbird","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faantti%2Fmcp-netbird","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faantti%2Fmcp-netbird/lists"}