list_netbird_peersLABSCO SUMMARY
Network state becomes a question rather than a dashboard tour.
Peers, groups, policies and posture checks are all readable from one connection, so "why can this machine reach that one" can be traced across the objects that decide it without clicking through four screens.
What it is
A read-only window onto a NetBird network. It maps a selected set of NetBird API resources one-to-one onto tools, so what you can ask for is exactly what the API publishes. The author describes the project as still in development.
What you get
- Every peer on the network, and the ingress port allocations for a given peer
- The groups, and the access policies defined over them
- Posture checks, so the conditions a device has to meet are readable alongside the policies that reference them
- Networks and nameserver groups, for the routing and DNS side of the configuration
- Read access only — nothing here changes the network's configuration
- The API host is configurable, so a self-hosted NetBird works the same way as the managed one
Requirements
A NetBird API token, supplied as NETBIRD_API_TOKEN. The API host defaults to api.netbird.io — point it at your own if you self-host. Install with Go, or through Smithery for a desktop client.
Setup effort
One command plus a key — go install github.com/aantti/mcp-netbird/cmd/mcp-netbird@latest, then supply credentials
USE CASES
01
Working out why one machine cannot reach another
Read both peers, find the groups they belong to, and check the policies defined over those groups — the answer is almost always in that chain.
02
Auditing who has access to what
Walk the policies alongside the groups they apply to, so the access model is read as it is configured rather than as it was described in a document.
03
Checking which devices meet your requirements
Read the posture checks and the peers together to see which machines satisfy the conditions the policies rely on.
04
Taking stock of the fleet
Pull every peer in one call for an inventory — what is connected, what is stale, what nobody remembers adding.
05
Debugging name resolution inside the network
Read the nameserver groups and the networks they serve, which is where an internal hostname that will not resolve usually turns out to be misconfigured.
06
Reviewing what a peer exposes
List the ingress port allocations for a specific peer to see which ports are reachable on it, rather than inferring it from the policy set.
7 tools
Listed in project docs. Your client may show a different list.
list_netbird_port_allocationslist_netbird_groupslist_netbird_policieslist_netbird_posture_checkslist_netbird_networkslist_netbird_nameserversBEFORE YOU INSTALL
What to know first
Tools you get
7 tools named in the project's documentation.
Requires
- mcp-netbird on PATH
- NETBIRD_API_TOKEN in your environment
INSTALLATION
Connect your client
Server setup
TERMINAL
go install github.com/aantti/mcp-netbird/cmd/mcp-netbird@latestMCP Clients
Windsurf, Claude Desktop
JSON
{
"mcpServers": {
"netbird": {
"command": "mcp-netbird",
"args": [],
"env": {
"NETBIRD_API_TOKEN": "<YOUR_NETBIRD_API_TOKEN>"
}
}
}
}ToolHive
TOOLHIVE · TERMINAL
git clone https://github.com/aantti/mcp-netbird
cd mcp-netbird
docker build -t mcp-netbird-sse:v1 -f Dockerfile.sse .
thv secret set netbird
thv run --secret netbird,target=NETBIRD_API_TOKEN --transport sse --name thv-mcp-netbird --port 8080 --target-port 8001 mcp-netbird-sse:v1
