Netbird

Lista y analiza los peers de red, grupos, políticas y más de Netbird.

Documentación

Servidor MCP de Netbird

Un servidor Model Context Protocol (MCP) para Netbird.

Este proyecto se deriva del Servidor MCP para Grafana de Grafana Labs y está licenciado bajo la misma Licencia Apache 2.0.

También utiliza MCP Go de Mark III Labs.

Nota: este proyecto aún está en desarrollo.

Instalación

Instalación desde el código fuente

Clonar el repositorio

git clone https://github.com/aantti/mcp-netbird

Compilar e instalar

cd mcp-netbird && \
make install

Instalación desde GitHub

go install github.com/aantti/mcp-netbird/cmd/mcp-netbird@latest

Instalación mediante Smithery

Para instalar Netbird MCP Server para Claude Desktop automáticamente mediante Smithery:

npx -y @smithery/cli install @aantti/mcp-netbird --client claude

Configuración

El servidor requiere las siguientes variables de entorno:

NETBIRD_API_TOKEN: Tu token de API de Netbird
NETBIRD_HOST (opcional): El host de la API de Netbird (por defecto es api.netbird.io)

Características

Este servidor utiliza la API de Netbird para proporcionar a los LLMs información sobre la red de Netbird. Actualmente es un mapeo 1:1 de recursos seleccionados de solo lectura de la API de Netbird a herramientas.

Utiliza la API de Netbird para acceder a la configuración y el estado
Punto final de API configurable
Autenticación segura basada en tokens para la API de Netbird

Herramientas

Herramienta	Descripción	API de Netbird
`list_netbird_peers`	Todos los peers	Listar todos los peers
`list_netbird_port_allocations`	Todos los puertos de entrada para `peerId`	Listar todas las asignaciones de puertos
`list_netbird_groups`	Todos los grupos	Listar todos los grupos
`list_netbird_policies`	Todas las políticas	Listar todas las políticas
`list_netbird_posture_checks`	Todas las comprobaciones de postura	Listar todas las comprobaciones de postura
`list_netbird_networks`	Todas las redes	Listar todas las redes
`list_netbird_nameservers`	Todos los grupos de servidores de nombres	Listar todos los grupos de servidores de nombres

Añadir herramientas

Para añadir nuevas herramientas:

Crea un nuevo archivo en tools (por ejemplo, tools/users.go), posiblemente usando el código existente como plantilla
Añade los detalles de la ruta de API y de la respuesta al nuevo archivo
Añade la herramienta a func newServer() en cmd/main.go

Uso

Obtén tu token de API de Netbird desde la consola de administración de Netbird.
Instala el binario mcp-netbird usando uno de los métodos de instalación anteriores. Asegúrate de que el binario esté en tu PATH.
Añade la configuración del servidor a tu archivo de configuración de cliente. Por ejemplo, para Codeium Windsurf añade lo siguiente a ~/.codeium/windsurf/mcp_config.json:
```
{
  "mcpServers": {
    "netbird": {
      "command": "mcp-netbird",
      "args": [],
      "env": {
        "NETBIRD_API_TOKEN": "<your-api-token>"
      }
    }
  }
}
```

Para más información sobre cómo añadir una configuración similar a Claude Desktop, consulta aquí.

Nota: si ves algo parecido a [netbird] [error] spawn mcp-netbird ENOENT en los registros de Claude Desktop, necesitas especificar la ruta completa a mcp-netbird. En macOS, los registros de Claude están en ~/Library/Logs/Claude.

Intenta hacer preguntas como "¿Puedes explicarme mis peers, grupos y políticas de Netbird?"

claude-desktop-mcp-netbird

Docker

Construye una imagen y etiquétala:

docker build -t mcp-netbird-sse:v1 -f Dockerfile.sse .

Ejecuta la imagen:

docker run --name mcp-netbird -p 8001:8001 -e NETBIRD_API_TOKEN=<your-api-token> mcp-netbird-sse:v1

ToolHive

ToolHive (thv) es una utilidad ligera diseñada para simplificar el despliegue y la gestión de servidores MCP.

Puedes usar ToolHive para desplegar y ejecutar Netbird MCP de la siguiente manera:

Instala thv como se describe en el README de ToolHive.
Añade el token de API de Netbird a los secretos de thv:

thv secret set netbird

Construye una imagen SSE como se describe en la sección de Docker anterior
Inicia Netbird MCP con thv run en el puerto 8080:

thv run --secret netbird,target=NETBIRD_API_TOKEN --transport sse --name thv-mcp-netbird --port 8080 --target-port 8001 mcp-netbird-sse:v1

Cuando quieras detener el servidor, usa:

thv stop thv-mcp-netbird

Desarrollo

¡Las contribuciones son bienvenidas! Por favor, abre un issue o envía un pull request si tienes sugerencias o mejoras.

Este proyecto está escrito en Go. Instala Go siguiendo las instrucciones para tu plataforma.

Para ejecutar el servidor manualmente, usa:

export NETBIRD_API_TOKEN=your-token && \
go run cmd/mcp-netbird/main.go

O en modo SSE:

export NETBIRD_API_TOKEN=your-token && \
go run cmd/mcp-netbird/main.go --transport sse --sse-address :8001

Depuración

El MCP Inspector es una herramienta interactiva para desarrolladores para probar y depurar servidores MCP. Lee más al respecto aquí.

Así es como se inicia el MCP Inspector:

export NETBIRD_API_TOKEN=your-token && \
npx @modelcontextprotocol/inspector

El servidor Netbird MCP puede probarse con el tipo de transporte stdio o SSE. Para stdio, especifica la ruta completa a mcp-netbird en la interfaz.

Pruebas

TODO: añadir más pruebas

Linting

Para hacer lint del código, ejecuta:

make lint

Licencia

Este proyecto está licenciado bajo la Licencia Apache, Versión 2.0.

Este proyecto incluye software desarrollado en Grafana Labs (https://grafana.com/).

Este proyecto incluye software desarrollado en Mark III Labs (https://github.com/mark3labs/mcp-go).