Molayo

© 2026 Molayo

GitHub요약2026. 06. 01. 09:00

Pixelworlds/opnsense-mcp-server

요약

OPNsense 방화벽 관리를 위한 모듈형 Model Context Protocol(MCP) 서버입니다. TypeScript 기반의 타입 안전성을 제공하며, AI 어시스턴트가 2,000개 이상의 방화벽 관리 메서드에 안전하게 접근할 수 있도록 돕습니다.

핵심 포인트

  • 88개의 모듈형 도구를 통해 2,000개 이상의 API 메서드 지원
  • TypeScript 기반의 완전한 타입 안전성 제공
  • Claude Desktop 및 Cursor 등 MCP 호환 클라이언트와 연동 가능
  • 64개의 플러그인 모듈에 대한 선택적 지원

타입 안전(Type-safe)한 TypeScript 인터페이스를 통해 2,000개 이상의 OPNsense 방화벽 관리 메서드에 접근할 수 있는 88개의 모듈 기반 도구를 제공하는 모듈형 Model Context Protocol (MCP) 서버입니다.

모듈형 아키텍처 (Modular Architecture)

  • 2,000개 이상의 개별 도구 대신 88개의 논리적 도구(모듈당 하나) 제공
    완전한 API 커버리지 (Complete API Coverage)
  • 752개의 코어 메서드 및 1,271개의 플러그인 메서드에 접근 가능
    타입 안전 (Type-Safe)
  • @richard-stovall/opnsense-typescript-client v0.5.3을 통한 완전한 TypeScript 지원
    플러그인 지원 (Plugin Support)
  • 64개 플러그인 모듈에 대한 선택적 지원
    스마트한 조직화 (Smart Organization)
  • 더 쉬운 탐색을 위해 관련 작업이 모듈별로 그룹화됨

이 MCP 서버는 AI 어시스턴트(Claude Desktop 등)와 사용자의 OPNsense 방화벽 사이에서 가교 역할을 하며, 모듈형 도구 인터페이스를 통해 안전한 API 접근을 제공합니다.

이 패키지는 Claude Desktop, Cursor 또는 기타 MCP 호환 클라이언트와 같은 AI 어시스턴트와 함께 MCP (Model Context Protocol) 서버로 사용하도록 설계되었습니다.

  • Node.js 18 이상
  • API 접근이 활성화된 OPNsense 방화벽
  • OPNsense 설치 환경에서 발급받은 API 키(API key) 및 비밀키(Secret)

npm install -g @richard-stovall/opnsense-mcp-server

Claude Desktop 설정 파일에 다음을 추가하세요:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
"mcpServers": {
"opnsense": {
...

명령줄 인수(Command Line Arguments) 사용 시:

{
"mcpServers": {
"opnsense": {
...

플러그인 도구 활성화:
64개의 모든 플러그인 모듈 도구를 포함하려면, args에 "--plugins"를 추가하거나 env에 "INCLUDE_PLUGINS": "true"를 설정하세요.

설정이 완료되면 Claude에게 다음과 같이 질문하여 연결을 테스트할 수 있습니다:

  • "사용 가능한 MCP 도구는 무엇인가요?"
  • "core_manage를 사용하여 시스템 상태를 가져오세요"
  • "firewall_manage를 사용하여 모든 에일리어스(aliases)를 검색하세요"
  • "interfaces_manage를 사용하여 모든 네트워크 인터페이스를 나열하세요"

연결 문제 (Connection Issues):

  • OPNsense API가 활성화되어 있는지 확인하세요
  • API 키에 적절한 권한이 있는지 확인하세요
  • IP/호스트 이름(hostname)에 귀하의 머신에서 접근 가능한지 확인하세요
  • 자체 서명된 인증서(self-signed certificates)를 사용하는 경우 --no-verify-ssl을 사용하거나

"OPNSENSE_VERIFY_SSL": "false"를 설정하세요.

서버 로그 보기 (View Server Logs):
Claude Desktop 로그를 확인하여 MCP 서버에서 발생하는 오류 메시지가 있는지 확인하세요.

수동 테스트 (Test Manually):
Claude Desktop에서 사용하기 전에 서버를 수동으로 테스트할 수 있습니다:

node /path/to/opnsense-mcp-server/index.js \
--url https://YOUR-OPNSENSE-IP \
--api-key YOUR-API-KEY \
...

다음과 같은 출력이 나와야 합니다:

OPNsense MCP server v0.6.0 (modular) started
Core tools: 24 modules
Plugin tools: 64 modules (disabled)
...

Cursor 설정에 추가하세요 (프로젝트 내의 .cursor/mcp.json 또는 전역 설정인 ~/.cursor/mcp.json):

{
"mcpServers": {
"opnsense": {
...

서버는 환경 변수(environment variables)를 통해 설정을 수락합니다:

OPNSENSE_URL

  • OPNsense 호스트 URL (필수)

OPNSENSE_API_KEY

  • 인증을 위한 API 키 (필수)

OPNSENSE_API_SECRET

  • 인증을 위한 API 비밀키 (필수)

INCLUDE_PLUGINS

  • 64개의 플러그인 모듈 도구를 활성화하려면 "true"로 설정 (선택 사항)

OPNSENSE_VERIFY_SSL

  • SSL 검증을 비활성화하려면 "false"로 설정 (개발 용도로만 사용)

모듈형 MCP 서버는 AI 어시스턴트에게 88개의 모듈 기반 도구를 제공합니다. 각 도구는 하나의 OPNsense 모듈을 나타내며, 작업을 지정하기 위한 method 파라미터를 수락합니다.

도구 사용 패턴 (Tool Usage Pattern):

{
"tool": "firewall_manage",
"arguments": {
...

프롬프트 예시 (Example prompts):

  • "core_manage를 사용하여 시스템 상태를 확인하세요"
  • "firewall_manage를 사용하여 모든 방화벽 에일리어스(firewall aliases)를 나열하세요"
  • "interfaces_manage를 사용하여 네트워크 인터페이스 정보를 가져오세요"
  • "plugin_nginx_manage를 사용하여 웹 서버 설정을 확인하세요"
  • "diagnostics_manage를 사용하여 ARP 테이블을 보세요"

모듈형 접근 방식은 관련 기능을 쉽게 찾을 수 있게 해줍니다. 모든 방화벽 작업은 firewall_manage에 있으며, 모든 VPN 작업은 각각의 모듈(openvpn_manage, ipsec_manage 등)에 있습니다.

, wireguard_manage

).

각 도구(Tool)는 해당 모듈 내의 모든 메서드(Method)에 대한 접근을 제공합니다:

도구 이름 (Tool Name)설명 (Description)예시 메서드 (Example Methods)
core_manage핵심 시스템 기능 (Core system functions)backupBackups , systemReboot , firmwareInfo
firewall_manage방화벽 규칙 및 별칭 (Firewall rules & aliases)aliasSearchItem , filterAddRule , natSearchRule
interfaces_manage네트워크 인터페이스 (Network interfaces)getInterfaces , vlanAddItem , setInterface
diagnostics_manage시스템 진단 (System diagnostics)interfaceGetArp , systemActivityGetActivity
auth_manage인증 (Authentication)userSearchUser , groupSearchGroup
firmware_manage펌웨어 업데이트 (Firmware updates)check , update , upgrade , changelog
openvpn_manageOpenVPNinstancesSearch , instancesAdd , serviceReconfigure
ipsec_manageIPsec VPNtunnelSearchPhase1 , connectionStatus
wireguard_manageWireGuard VPNserverSearchServer , clientSearchClient
unbound_manageDNS 리졸버 (DNS resolver)hostOverrideSearchItem , serviceReconfigure
dhcpv4_manageDHCP 서버 (DHCP server)searchLease , addReservation

인기 있는 플러그인 모듈 (Popular plugin modules):

도구 이름 (Tool Name)설명 (Description)예시 메서드 (Example Methods)
plugin_nginx_manageNginx 웹 서버 (Nginx web server)generalGet , upstreamSearchUpstream
plugin_haproxy_manageHAProxy 로드 밸런서 (HAProxy load balancer)serverSearchServer , statsGet
plugin_caddy_manageCaddy 웹 서버 (Caddy web server)reverseProxySearchDomain , serviceStatus
plugin_bind_manageBIND DNSdomainSearchDomain , recordSearchRecord
plugin_acmeclient_manageLet's EncryptcertificatesSearch , certificatesIssue

서버에 기여하거나 커스텀하고 싶다면:

# 저장소 클론 (Clone the repository)
git clone https://github.com/richard-stovall/opnsense-mcp-server.git
cd opnsense-mcp-server
...

yarn generate-tools # 도구 정의 생성 (Generate tool definitions)
yarn build # 서버 빌드 (Build the server)
yarn build:all # 도구 생성 및 빌드 (Generate tools and build)
...

런타임 (Runtime): TypeScript 실행을 위한 tsx를 포함한 Node.js
패키지 매니저 (Package Manager): Plug'n'Play를 사용하는 Yarn 4.9.2
빌드 시스템 (Build System): 단일 파일로의 단순한 TypeScript 컴파일
언어 (Language): TypeScript 5.3+
MCP SDK: @modelcontextprotocol/sdk
API 클라이언트 (API Client): @richard-stovall/opnsense-typescript-client
검증 (Validation): 스키마 검증을 위한 Zod
테스트 (Testing): TypeScript를 지원하는 Jest

이 서버는 다음을 제공하는 @richard-stovall/opnsense-typescript-client 패키지를 사용합니다:

  • 모든 API 호출에 대한 완전한 타입 안정성 (Type safety)
  • 내장된 에러 핸들링 (Error handling) 및 재시도 (Retries)
  • 601개의 모든 OPNsense API 엔드포인트 (Endpoints) 지원
  • 현대적인 Fetch API 기반 구현
const response = await client.system.getStatus();
return {
content: [
...

기여를 환영합니다! 언제든지 Pull Request를 제출해 주세요.

  • 저장소(Repository)를 포크(Fork)합니다.
  • 기능 브랜치(Feature branch)를 생성합니다 (git checkout -b feature/AmazingFeature)
  • 변경 사항을 커밋(Commit)합니다 (git commit -m 'Add some AmazingFeature')
  • 브랜치로 푸시(Push)합니다 (git push origin feature/AmazingFeature)
  • Pull Request를 오픈합니다.

이 프로젝트는 MIT 라이선스(MIT License) 하에 라이선스가 부여됩니다 - 자세한 내용은 LICENSE 파일을 참조하세요.

  • Anthropic의 Model Context Protocol을 기반으로 구축되었습니다.
  • @richard-stovall/opnsense-typescript-client에 의해 구동됩니다.
  • OPNsense 커뮤니티에서 영감을 받았습니다.

OPNsense 커뮤니티를 위한 사랑을 담아 제작되었습니다.

AI 자동 생성 콘텐츠

본 콘텐츠는 GitHub AI Tools의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0