Netbird MCP 서버

Netbird 용 MCP( Model Context Protocol ) 서버.

이 프로젝트는 Grafana Labs의 Grafana용 MCP 서버 에서 파생되었으며 동일한 Apache 라이선스 2.0에 따라 라이선스가 부여되었습니다.

또한 Mark III Labs의 MCP Go를 사용합니다.

참고: 이 프로젝트는 아직 개발 중입니다.

설치 중

소스에서 설치

저장소를 복제합니다

지엑스피1

빌드하고 설치하세요

cd mcp-netbird && \
make install

GitHub에서 설치

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

Smithery를 통해 설치

Smithery를 통해 Claude Desktop에 Netbird MCP 서버를 자동으로 설치하려면:

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

구성

서버에는 다음과 같은 환경 변수가 필요합니다.

NETBIRD_API_TOKEN : Netbird API 토큰
NETBIRD_HOST (선택 사항): Netbird API 호스트(기본값은 api.netbird.io )

특징

이 서버는 Netbird API를 사용하여 LLM에 Netbird 네트워크 정보를 제공합니다. 현재는 선택된 읽기 전용 Netbird API 리소스를 도구에 1:1로 매핑합니다.

[x] Netbird API를 사용하여 구성 및 상태에 액세스합니다.
[x] 구성 가능한 API 엔드포인트
[x] Netbird API를 위한 보안 토큰 기반 인증

도구

도구	설명	넷버드 API
`list_netbird_peers`	모든 동료들	모든 피어 나열
`list_netbird_port_allocations`	`peerId` 에 대한 모든 수신 포트	모든 포트 할당 나열
`list_netbird_groups`	모든 그룹	모든 그룹 나열
`list_netbird_policies`	모든 정책	모든 정책 나열
`list_netbird_posture_checks`	모든 자세 검사	모든 자세 점검 목록
`list_netbird_networks`	모든 네트워크	모든 네트워크 나열
`list_netbird_nameservers`	모든 네임서버 그룹	모든 네임서버 그룹 나열

도구 추가

새로운 도구를 추가하려면:

tools 에 새 파일을 만듭니다(예: tools/users.go ). 기존 코드를 템플릿으로 사용할 수 있습니다.
새 파일에 API 경로 및 응답 세부 정보 추가
cmd/main.go 의 func newServer() 에 도구를 추가합니다.

용법

Netbird 관리 콘솔에서 Netbird API 토큰을 받으세요.
위의 설치 방법 중 하나를 사용하여 mcp-netbird 바이너리를 설치하세요. 바이너리가 PATH에 있는지 확인하세요.
클라이언트 설정 파일에 서버 설정을 추가하세요. 예를 들어, Codeium Windsurf의 경우 ~/.codeium/windsurf/mcp_config.json 파일에 다음을 추가하세요.
{ "mcpServers": { "netbird": { "command": "mcp-netbird", "args": [], "env": { "NETBIRD_API_TOKEN": "<your-api-token>" } } } }

Claude Desktop에 유사한 구성을 추가하는 방법에 대한 자세한 내용은 여기를 참조하세요.

참고: Claude Desktop 로그에 [netbird] [error] spawn mcp-netbird ENOENT 와 같은 오류가 표시되면 mcp-netbird 의 전체 경로를 지정해야 합니다. macOS Claude의 로그는 ~/Library/Logs/Claude 에 있습니다.

"저희 Netbird 동료, 그룹 및 정책에 대해 설명해 주시겠습니까?"와 같은 질문을 해보세요.

도커

이미지를 만들고 태그를 지정하세요.

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

이미지를 실행합니다:

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

툴하이브

ToolHive (thv)는 MCP 서버의 배포와 관리를 단순화하도록 설계된 가벼운 유틸리티입니다.

ToolHive를 사용하면 다음과 같이 Netbird MCP를 배포하고 실행할 수 있습니다.

ToolHive README 에 설명된 대로 thv 설치합니다.
thv secrets에 Netbird API 토큰을 추가합니다.

thv secret set netbird

위의 Docker 섹션에 설명된 대로 SSE 이미지를 빌드합니다.
포트 8080에서 thv run 로 Netbird MCP를 시작합니다.

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

서버를 중지하려면 다음을 사용하세요.

thv stop thv-mcp-netbird

개발

기여를 환영합니다! 제안이나 개선 사항이 있으시면 이슈를 개설하거나 풀 리퀘스트를 제출해 주세요.

이 프로젝트는 Go로 작성되었습니다. 플랫폼별 지침에 따라 Go를 설치하세요.

서버를 수동으로 실행하려면 다음을 사용하세요.

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

또는 SSE 모드에서:

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

디버깅

MCP Inspector는 MCP 서버를 테스트하고 디버깅하는 데 사용되는 대화형 개발자 도구입니다. 자세한 내용은 여기를 참조하세요.

MCP Inspector를 시작하는 방법은 다음과 같습니다.

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

Netbird MCP 서버는 stdio 또는 SSE 전송 유형으로 테스트할 수 있습니다. stdio 의 경우, UI에서 mcp-netbird 의 전체 경로를 지정하세요.

테스트

TODO: 더 많은 테스트 추가

린팅

코드를 린트하려면 다음을 실행하세요.

make lint

특허

이 프로젝트는 Apache 라이선스 버전 2.0 에 따라 라이선스가 부여되었습니다.

이 프로젝트에는 Grafana Labs( https://grafana.com/ )에서 개발된 소프트웨어가 포함되어 있습니다.

이 프로젝트에는 Mark III Labs( https://github.com/mark3labs/mcp-go )에서 개발된 소프트웨어가 포함되어 있습니다.

Integrations