Skip to main content
Glama
deenesjakoruzh
lucamarien

OPNsense MCP Server

by lucamarien
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

OPNsense MCP 서버

OPNsense 방화벽을 Claude Code, Cursor 및 기타 MCP 호환 도구와 같은 AI 어시스턴트를 통해 관리하기 위한 보안 Model Context Protocol (MCP) 서버입니다.

10개 도메인에 걸친 81개 도구: 시스템, 방화벽, 네트워크, DNS, DHCP, VPN, HAProxy, 서비스, 진단 및 보안.

요구 사항

  • Python 3.11 이상

  • OPNsense 24.7 이상 — MCP 서버는 OPNsense 24.7에서 도입된 MVC 기반 API 엔드포인트에 의존합니다. 이전 버전은 호환되지 않는 다른 API 구조를 사용합니다. 서버는 첫 연결 시 OPNsense 버전을 자동 감지하여 올바른 엔드포인트 명명 방식(camelCase for pre-25.7, snake_case for 25.7+)을 선택합니다. OPNsense 26.x는 변경된 펌웨어 상태 응답 형식을 포함하여 완전히 지원됩니다.

Related MCP server: OPNsense MCP Server

보안 모델

이 MCP 서버는 보안을 최우선으로 설계되었습니다:

  • 기본적으로 읽기 전용 — 쓰기 작업은 OPNSENSE_ALLOW_WRITES=true를 통한 명시적 동의가 필요합니다

  • 저장점/롤백 (OPNsense < 26.7 전용) — OPNsense가 여전히 저장점 API를 제공하는 경우, 방화벽 수정은 내장된 60초 자동 복귀 기능을 사용합니다. 변경 사항은 명시적으로 확인되어야 하며, 그렇지 않으면 자동으로 롤백됩니다. OPNsense 26.7은 해당 API를 상위 버전에서 제거했습니다 — 서버는 런타임에 누락된 엔드포인트를 감지하고 자동 롤백 없이 방화벽 변경 사항을 즉시 적용합니다

  • 엔드포인트 차단 목록 — 위험한 엔드포인트(halt, reboot, poweroff, firmware update/upgrade)는 API 클라이언트 수준에서 하드 차단되며 절대 호출할 수 없습니다

  • API 전용 — SSH 액세스 없음, 명령 실행 없음, 직접적인 구성 파일 조작 없음

  • 로컬 전송 — STDIO 전용, 네트워크에 노출된 HTTP/SSE 엔드포인트 없음

  • 자격 증명 노출 없음 — API 키는 도구 출력, 로그 또는 오류 메시지에 절대 포함되지 않습니다

  • 입력 검증 — 호스트 이름 매개변수는 셸 메타문자 주입에 대해 검증됩니다

  • 민감 데이터 제거 — 구성 백업은 기본적으로 비밀번호와 키를 제거합니다

빠른 시작

1. OPNsense API 키 생성

  1. OPNsense 웹 인터페이스에 로그인합니다

  2. 시스템 > 액세스 > 사용자로 이동합니다

  3. 기존 사용자를 편집하거나 전용 API 사용자를 생성합니다:

    • 프로덕션 사용의 경우 필요한 권한만 가진 전용 사용자(예: mcp-api)를 생성합니다

    • 읽기 전용 액세스의 경우 사용자를 읽기 전용 API 액세스 권한이 있는 그룹에 할당합니다

  4. API 키 섹션까지 아래로 스크롤하고 + 버튼을 클릭합니다

  5. 키/시크릿 쌍이 생성되고 파일(apikey.txt)이 다운로드됩니다

  6. 파일에는 key=your-api-key-here 및 secret=your-api-secret-here 두 줄이 포함되어 있습니다

  7. 이러한 자격 증명을 안전하게 보관하세요 — 시크릿은 OPNsense에서 다시 검색할 수 없습니다

팁: 읽기 전용 설정(시작 시 권장)의 경우 권한을 변경할 필요가 없습니다 — 기본 API 액세스로 모든 읽기 전용 도구에 충분합니다.

2. 설치

# Using pip
pip install opnsense-mcp-server

# Using uv (recommended for isolated environments)
uv pip install opnsense-mcp-server

# Using Docker
docker pull uhlenheide/opnsense-mcp-server

# From source
git clone https://github.com/lucamarien/opnsense-mcp-server
cd opnsense-mcp-server
pip install -e .

Docker 이미지: 공식 이미지는 uhlenheide/opnsense-mcp-server이며, 이 저장소의 .github/workflows/publish-docker.yml에서 모든 v* 태그에 대해 게시됩니다. lucamarien/opnsense-mcp-server 이미지는 존재하지 않습니다 — 이전 README 버전에서 실수로 명명되었습니다.

3. AI 어시스턴트 구성

Claude Code

프로젝트의 .mcp.json에 추가합니다:

{
  "mcpServers": {
    "opnsense": {
      "command": "opnsense-mcp",
      "env": {
        "OPNSENSE_URL": "https://192.168.1.1/api",
        "OPNSENSE_API_KEY": "your-api-key-here",
        "OPNSENSE_API_SECRET": "your-api-secret-here",
        "OPNSENSE_VERIFY_SSL": "false",
        "OPNSENSE_ALLOW_WRITES": "false"
      }
    }
  }
}

대안: opnsense-mcp CLI가 PATH에 없는 경우 "command": "python", "args": ["-m", "opnsense_mcp"]를 사용합니다.

또는 ~/.claude/claude_code_config.json에 전역으로 추가합니다.

Claude Code (Docker)

{
  "mcpServers": {
    "opnsense": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "OPNSENSE_URL=https://192.168.1.1/api",
        "-e", "OPNSENSE_API_KEY=your-api-key-here",
        "-e", "OPNSENSE_API_SECRET=your-api-secret-here",
        "-e", "OPNSENSE_VERIFY_SSL=false",
        "-e", "OPNSENSE_ALLOW_WRITES=false",
        "uhlenheide/opnsense-mcp-server"
      ]
    }
  }
}

Cursor

Cursor MCP 설정(설정 > MCP)에 추가합니다:

{
  "mcpServers": {
    "opnsense": {
      "command": "opnsense-mcp",
      "env": {
        "OPNSENSE_URL": "https://192.168.1.1/api",
        "OPNSENSE_API_KEY": "your-api-key-here",
        "OPNSENSE_API_SECRET": "your-api-secret-here",
        "OPNSENSE_VERIFY_SSL": "false"
      }
    }
  }
}

구성

환경 변수

기본값

설명

OPNSENSE_URL

(필수)

OPNsense API 기본 URL (/api로 끝나야 함)

OPNSENSE_API_KEY

(필수)

OPNsense 사용자 설정의 API 키

OPNSENSE_API_SECRET

(필수)

OPNsense 사용자 설정의 API 시크릿

OPNSENSE_VERIFY_SSL

true

SSL 인증서 검증 (false는 자체 서명 인증서용)

OPNSENSE_ALLOW_WRITES

false

쓰기 작업 활성화 (방화벽 규칙, 서비스 제어)

사용자 지정 포트: OPNsense 웹 GUI가 비표준 포트(예: 10443)에서 실행되는 경우 URL에 포함하세요: https://192.168.1.1:10443/api

사용 가능한 도구 (81개)

시스템 (7개 도구)

도구

설명

opn_system_status

펌웨어 버전, 제품 이름, 아키텍처를 포함한 시스템 정보

opn_list_services

모든 서비스와 실행 상태를 나열합니다. 매개변수: search, limit

opn_gateway_status

게이트웨이 가용성, 지연 시간 및 dpinger 상태 확인

opn_download_config

선택적 민감 데이터 제거 기능이 있는 config.xml 백업을 다운로드합니다. 매개변수: include_sensitive (기본값: false — 비밀번호와 키는 편집됨)

opn_scan_config

전체 구성을 스캔하고 섹션으로 구문 분석하며 런타임 인벤토리(펌웨어, 플러그인, DHCP, DNS, 인터페이스, 서비스)를 수집합니다. 결과는 세션별로 캐시됩니다. 매개변수: force

opn_get_config_section

특정 구성 섹션을 구조화된 JSON으로 가져옵니다. 매개변수: section, include_sensitive

opn_mcp_info

MCP 서버 버전, 쓰기 모드 상태, 감지된 OPNsense 버전, API 스타일 및 방화벽 쓰기가 여전히 저장점/롤백 보호를 받는지 여부

네트워크 (5개 도구)

도구

설명

opn_interface_stats

인터페이스별 트래픽 통계 (바이트 인/아웃, 패킷, 오류)

opn_arp_table

IP-to-MAC 주소 매핑을 보여주는 ARP 테이블

opn_ndp_table

IPv6-to-MAC 주소 매핑을 보여주는 NDP(이웃 발견 프로토콜) 테이블

opn_ipv6_status

모든 인터페이스의 IPv6 구성 및 주소 상태 (방법, 라이브 주소, 요약)

opn_list_static_routes

구성된 정적 경로. 매개변수: search, limit

방화벽 (21개 도구)

도구

설명

쓰기

opn_list_firewall_rules

MVC 방화벽 필터 규칙을 나열합니다. 매개변수: search, limit

아니요

opn_list_firewall_aliases

별칭 정의(IP 목록, 포트 그룹, GeoIP, URL)를 나열합니다. 매개변수: search, limit

아니요

opn_list_nat_rules

NAT 포트 포워딩(DNAT) 규칙을 나열합니다. 매개변수: search, limit

아니요

opn_list_firewall_categories

방화벽 규칙 범주와 해당 UUID를 나열합니다. 매개변수: search, limit

아니요

opn_firewall_log

클라이언트 측 필터링이 적용된 최근 방화벽 로그 항목입니다. 매개변수: source_ip, destination_ip, action, interface, limit

아니요

opn_confirm_changes

보류 중인 변경 사항을 확인하고 60초 자동 롤백을 취소합니다(OPNsense < 26.7, 26.7 이상에서는 not_applicable을 반환하는 no-op). 매개변수: revision

예

opn_toggle_firewall_rule

세이브포인트로 규칙의 활성화/비활성화 상태를 전환합니다(OPNsense < 26.7). 매개변수: uuid

예

opn_add_firewall_rule

세이브포인트로 새 필터 규칙을 생성합니다(OPNsense < 26.7). 매개변수: action, direction, interface, ip_protocol, protocol, source_net, destination_net, destination_port, description

예

opn_delete_firewall_rule

세이브포인트로 UUID로 필터 규칙을 삭제합니다(OPNsense < 26.7). 매개변수: uuid

예

opn_add_alias

새 별칭을 생성합니다. 매개변수: name, alias_type, content, description

예

opn_add_nat_rule

세이브포인트로 NAT 포트 포워딩 규칙을 생성합니다(OPNsense < 26.7). 매개변수: destination_port, target_ip, interface, protocol, target_port, description

예

opn_add_firewall_category

새 방화벽 규칙 범주를 생성합니다. 매개변수: name, color

예

opn_delete_firewall_category

세이브포인트로 UUID로 방화벽 규칙 범주를 삭제합니다(OPNsense < 26.7). 매개변수: uuid

예

opn_set_rule_categories

세이브포인트로 방화벽 규칙에 범주를 할당합니다(OPNsense < 26.7). 매개변수: uuid, categories

예

opn_add_icmpv6_rules

RFC 4890에 따라 IPv6 운영에 필요한 필수 ICMPv6 규칙(NDP, RA, ping6)을 생성합니다. 매개변수: interface

예

opn_update_alias

기존 별칭(이름, 내용, 유형, 설명)을 업데이트합니다. 읽기-수정-쓰기 방식입니다. 매개변수: uuid, name, content, description, alias_type, enabled

예

opn_delete_alias

UUID로 별칭을 삭제합니다. 먼저 규칙 참조를 확인합니다. 매개변수: uuid

예

opn_toggle_alias

별칭의 활성화/비활성화 상태를 전환합니다. 매개변수: uuid

예

opn_update_firewall_rule

세이브포인트로 필터 규칙 필드를 업데이트합니다(OPNsense < 26.7). 매개변수: uuid, action, direction, interface, ip_protocol, protocol, source_net, source_not, source_port, destination_net, destination_not, destination_port, gateway, log, quick, sequence, categories, description, enabled

예

opn_update_nat_rule

세이브포인트로 NAT 포트 포워딩 규칙을 업데이트합니다(OPNsense < 26.7). 매개변수: uuid, interface, protocol, destination_port, target_ip, target_port, description, enabled

예

opn_delete_nat_rule

세이브포인트로 UUID로 NAT 포트 포워딩 규칙을 삭제합니다(OPNsense < 26.7). 매개변수: uuid

예

참고: 세이브포인트 보호는 OPNsense < 26.7에서만 제공됩니다. 26.7 이상에서는 이러한 도구가 변경 사항을 즉시 영구적으로 적용합니다 — 쓰기 작업 및 세이브포인트를 참조하세요.

DNS (13개 도구)

도구

설명

쓰기

opn_list_dns_overrides

Unbound 호스트 오버라이드(로컬 DNS 레코드)를 나열합니다. 매개변수: search, limit

아니요

opn_list_dns_forwards

DNS 포워드 영역(도메인별 서버)을 나열합니다. 매개변수: search, limit

아니요

opn_dns_stats

Unbound 리졸버 통계(쿼리, 캐시 적중, 가동 시간)

아니요

opn_reconfigure_unbound

보류 중인 DNS 리졸버 구성 변경 사항을 적용합니다

예

opn_add_dns_override

Unbound DNS 호스트 오버라이드(A/AAAA 레코드)를 추가하고 즉시 적용합니다. 매개변수: hostname, domain, server, description

예

opn_list_dnsbl

제공자 및 상태와 함께 DNSBL 차단 목록 구성을 나열합니다. 매개변수: search, limit

아니요

opn_get_dnsbl

UUID로 전체 DNSBL 구성(제공자, 허용 목록, 설정)을 가져옵니다. 매개변수: uuid

아니요

opn_set_dnsbl

DNSBL 설정을 업데이트합니다(읽기-수정-쓰기). 매개변수: uuid, enabled, providers, allowlists, blocklists, wildcards 등

예

opn_add_dnsbl_allowlist

덮어쓰지 않고 DNSBL 허용 목록에 도메인을 추가합니다. 매개변수: uuid, domains

예

opn_remove_dnsbl_allowlist

DNSBL 허용 목록에서 도메인을 제거합니다. 매개변수: uuid, domains

예

opn_update_dnsbl

DNSBL 차단 목록 파일을 다시 로드하고 Unbound를 재시작합니다(구성 변경 없음, 복구 도구)

예

opn_update_dns_override

Unbound DNS 호스트 오버라이드를 업데이트하고 즉시 적용합니다. 매개변수: uuid, hostname, domain, server, description, enabled

예

opn_delete_dns_override

Unbound DNS 호스트 오버라이드를 삭제하고 즉시 적용합니다. 매개변수: uuid

예

DHCP (8개 도구)

도구

설명

쓰기

opn_list_dhcp_leases

ISC DHCP 서버의 활성 DHCPv4 임대

아니요

opn_list_kea_leases

Kea DHCP 서버의 DHCPv4 임대. 매개변수: search, limit

아니요

opn_list_dnsmasq_leases

dnsmasq DNS/DHCP 서버의 DHCPv4 및 DHCPv6 임대. 매개변수: search, limit

아니요

opn_list_dnsmasq_ranges

구성된 DHCP 주소 범위(RA 구성이 포함된 DHCPv4 및 DHCPv6 모두). 매개변수: search, limit

아니요

opn_add_dnsmasq_range

새 DHCP 범위 생성(라우터 광고 구성이 포함된 IPv4 또는 IPv6). 매개변수: interface, start_addr, end_addr, prefix_len, ra_mode, lease_time, description

예

opn_reconfigure_dnsmasq

보류 중인 dnsmasq DNS/DHCP 구성 변경 사항 적용

예

opn_update_dnsmasq_range

DHCP 범위 업데이트(주소, 임대 시간, RA 구성) 후 적용. 매개변수: uuid, interface, start_addr, end_addr, prefix_len, ra_mode, lease_time, description, enabled

예

opn_delete_dnsmasq_range

UUID로 DHCP 범위 삭제 후 적용. 매개변수: uuid

예

VPN (도구 3개)

도구

설명

opn_wireguard_status

WireGuard 터널 및 피어 상태(os-wireguard 플러그인 필요)

opn_ipsec_status

IPsec VPN 터널 상태 — IKE(1단계) 및 ESP/AH(2단계) 세션

opn_openvpn_status

OpenVPN 연결 상태 — 인스턴스, 세션 및 경로

HAProxy (도구 8개)

HAProxy 로드 밸런서용 전체 구성 관리(os-haproxy 플러그인 필요).

도구

설명

쓰기

opn_haproxy_status

HAProxy 서비스 상태 및 백엔드 상태

아니요

opn_haproxy_search

유형별 HAProxy 리소스 검색. 매개변수: resource_type (frontends/backends/servers/acls/healthchecks/errorfiles/resolvers/mailers), search, limit

아니요

opn_haproxy_get

특정 리소스의 상세 구성 가져오기. 매개변수: resource_type, uuid

아니요

opn_haproxy_configtest

적용 전 HAProxy 구성 구문 검증

아니요

opn_haproxy_add

새 HAProxy 리소스 생성. 매개변수: resource_type, config (필드 값의 사전)

예

opn_haproxy_update

기존 HAProxy 리소스 업데이트(부분 업데이트). 매개변수: resource_type, uuid, config

예

opn_haproxy_delete

UUID로 HAProxy 리소스 삭제. 매개변수: resource_type, uuid

예

opn_reconfigure_haproxy

보류 중인 HAProxy 구성 변경 사항 적용

예

참고: HAProxy 변경 사항은 저장 지점(savepoint) 보호를 사용하지 않습니다 — 재구성 시 즉시 적용됩니다. opn_reconfigure_haproxy 전에 항상 opn_haproxy_configtest를 호출하세요.

서비스 (도구 11개)

도구

설명

쓰기

opn_list_acme_certs

ACME/Let's Encrypt 인증서 및 상태. 매개변수: search, limit

아니요

opn_list_cron_jobs

예약된 cron 작업. 매개변수: search, limit

아니요

opn_crowdsec_status

CrowdSec 보안 엔진 상태 및 위협 탐지

아니요

opn_crowdsec_alerts

CrowdSec 보안 경고(탐지된 위협). 매개변수: search, limit

아니요

opn_list_ddns_accounts

Dynamic DNS 계정 및 업데이트 상태. 매개변수: search, limit

아니요

opn_add_ddns_account

새 Dynamic DNS 계정 생성. 매개변수: service, hostname, username, password, checkip, interface, description

예

opn_reconfigure_ddclient

보류 중인 Dynamic DNS 구성 변경 사항 적용

예

opn_update_ddns_account

Dynamic DNS 계정 업데이트(비밀번호는 쓰기 전용). 매개변수: uuid, service, hostname, username, password, checkip, interface, description, enabled

예

opn_delete_ddns_account

UUID로 Dynamic DNS 계정 삭제. 매개변수: uuid

예

opn_mdns_repeater_status

mDNS 반복기 상태 및 구성

아니요

opn_configure_mdns_repeater

VLAN 간 장치 검색을 위한 mDNS 반복기 구성. 매개변수: enabled, interfaces

예

진단 (도구 4개)

도구

설명

쓰기

opn_ping

호스트에 ICMP ping 전송. 매개변수: host, count

아니요

opn_traceroute

호스트로의 경로 추적. 매개변수: host, protocol, ip_version

아니요

opn_dns_lookup

DNS 조회 수행. 매개변수: hostname, server (선택 사항)

아니요

opn_pf_states

pf 방화벽 상태 테이블(현재 연결). 매개변수: search, limit

아니요

보안 (도구 1개)

도구

설명

opn_security_audit

방화벽 규칙, DNS 보안, VPN 구성을 포함한 보안 상태 종합 감사

IPv6 지원

MCP를 통한 완전 자동화

  • IPv6 방화벽 규칙 — ip_protocol="inet6"로 규칙 생성 (OPNsense < 26.7에서는 savepoint로 보호됨)

  • HAProxy IPv6 바인딩 — [::]:443 또는 [2001:db8::1]:443 바인드 주소를 사용하는 프론트엔드

  • HAProxy IPv6 백엔드 — IPv6 주소를 사용하는 서버, 백엔드의 resolvePrefer: ipv6

  • IPv6 동적 DNS — IPv6 지원 checkip 방식을 사용하는 DDNS 계정

  • DHCPv6 범위 (dnsmasq) — 라우터 광고(Router Advertisement) 구성이 포함된 IPv6 DHCP 범위

  • DNS AAAA 레코드 — IPv6 주소를 사용하는 Unbound 호스트 오버라이드

  • IPv6 진단 — ip_version="6"을 사용한 Traceroute, 호스트 이름을 통한 ping

수동 GUI 구성 필요

이 설정들은 OPNsense에서 MVC API를 지원하지 않으므로 웹 GUI를 통해 구성해야 합니다:

  • WAN IPv6 설정 — DHCPv6 프리픽스 위임을 사용하는 PPPoE, 정적 IPv6, SLAAC

  • LAN IPv6 주소 지정 — Track Interface 모드, 정적 /64 할당, 프리픽스 ID

  • 인터페이스 할당 — WAN/LAN/OPT 역할에 물리적 포트 할당

  • 6to4/6rd 터널 — 전환 터널 메커니즘

알려진 제한 사항

  • ISC DHCP / Kea DHCPv6: 구현되지 않았습니다. DHCPv6 범위 및 라우터 광고에 대해서는 dnsmasq(현대적 기본값)만 지원됩니다. ISC DHCP는 더 이상 사용되지 않으며, Kea DHCPv6 임대 정보는 API에서 제한적으로만 확인할 수 있습니다.

  • radvd: 별도의 도구 세트로 구현되지 않았습니다. Dnsmasq는 범위 구성을 통해 라우터 광고를 기본적으로 처리합니다. 인터페이스당 하나의 RA 데몬만 실행해야 합니다.

  • 이중 스택 방화벽 규칙: inet46(이중 스택)은 MVC API 규칙(opn_add_firewall_rule)에서 올바르게 작동합니다. 그러나 레거시 XML 필터 규칙(GUI)의 inet46은 조용히 PF 출력을 생성하지 않습니다 — 이는 레거시 규칙에만 영향을 미치는 알려진 OPNsense 버그입니다.

  • 레거시 GUI 규칙: 기존 OPNsense GUI를 통해 생성된 방화벽 규칙은 MVC API를 통해 접근할 수 없습니다. 읽기 전용 접근에는 opn_get_config_section("filter")를 사용하세요.

권장 IPv6 마이그레이션 워크플로

  1. 수동(GUI): WAN IPv6 구성 (ISP의 DHCPv6-PD 또는 정적)

  2. 수동(GUI): LAN 인터페이스 구성 (프리픽스 위임을 위한 Track Interface 모드)

  3. MCP: RA 플래그와 함께 opn_add_dnsmasq_range를 통해 라우터 광고 구성

  4. MCP: IPv6 방화벽 규칙 생성 (NDP/RA/PMTUD를 위해 ICMPv6를 허용해야 함)

  5. MCP: opn_add_dns_override를 통해 IPv6 DNS 레코드 추가

  6. MCP: IPv6 checkip 방식으로 Dynamic DNS 구성

  7. MCP: HAProxy 프론트엔드에 IPv6 바인드 주소 추가

  8. MCP: opn_ping, opn_traceroute (ip_version="6"), opn_gateway_status로 검증

버전 호환성

OPNsense 버전

상태

24.7 (Thriving Tiger)

지원됨

25.1 (Ultimate Unicorn)

지원됨

25.7 (Visionary Viper)

지원됨 (snake_case API 자동 감지)

26.1+

지원됨

서버는 첫 연결 시 OPNsense 버전을 자동으로 감지하여 올바른 API 엔드포인트 명명 규칙(25.7 이전은 camelCase, 25.7 이후는 snake_case)을 선택합니다.

방화벽 규칙 참고: opn_list_firewall_rules는 MVC/자동화 API를 통해 관리되는 규칙을 표시합니다. OPNsense GUI를 통해 구성된 규칙은 이 API에서 접근할 수 없는 레거시 형식을 사용합니다. 이는 알려진 OPNsense 제한 사항입니다.

문제 해결

연결 문제

"Connection refused" 또는 시간 초과 오류

  • OPNSENSE_URL이 /api로 끝나는지 확인하세요 (예: https://192.168.1.1/api)

  • 비표준 포트를 사용하는 경우 포함하세요: https://192.168.1.1:10443/api

  • MCP 서버가 실행 중인 머신에서 OPNsense 웹 GUI에 접근할 수 있는지 확인하세요

SSL 인증서 오류

  • 자체 서명 인증서(기본 OPNsense 설정)를 사용하는 경우 OPNSENSE_VERIFY_SSL=false로 설정하세요

  • 프로덕션 환경에서는 OPNsense에 적절한 인증서를 설치하고 OPNSENSE_VERIFY_SSL=true를 유지하세요

인증 문제

401 Unauthorized

  • OPNSENSE_API_KEY와 OPNSENSE_API_SECRET이 올바른지 확인하세요

  • API 키는 대소문자를 구분합니다 — 다운로드한 apikey.txt에서 정확히 복사하세요

  • API 사용자가 OPNsense에서 비활성화되지 않았는지 확인하세요

  • API 사용자가 수행하려는 작업에 충분한 권한을 가지고 있는지 확인하세요

403 Forbidden

  • API 사용자에게 요청한 엔드포인트에 대한 권한이 없을 수 있습니다

  • 쓰기 작업의 경우 OPNSENSE_ALLOW_WRITES=true가 설정되어 있는지 확인하세요

도구별 문제

opn_list_firewall_rules가 빈 결과를 반환함

  • 이 도구는 레거시 GUI 규칙이 아닌 MVC/자동화 규칙만 표시합니다

  • 자동화 API 또는 opn_add_firewall_rule을 통해 규칙을 생성하면 해당 규칙을 볼 수 있습니다

opn_ping 시간 초과

  • 방화벽에 대상 호스트로의 경로가 없을 수 있습니다

  • opn_gateway_status로 게이트웨이 상태를 확인하세요

  • 기본 시간 초과는 30초입니다 (30회 폴링 주기)

opn_download_config에 [REDACTED] 값이 표시됨

  • 보안을 위한 기본 동작입니다. 비밀번호와 키를 포함하려면 include_sensitive=true를 전달하세요 (AI 대화에서는 주의해서 사용)

쓰기 작업이 "writes not enabled" 오류로 실패함

  • MCP 서버 구성에서 OPNSENSE_ALLOW_WRITES=true를 설정하세요

  • 안전을 위해 의도적으로 기본 비활성화되어 있습니다

Savepoint 확인 실패

  • revision 매개변수는 쓰기 작업에서 반환된 값과 정확히 일치해야 합니다

  • 확인은 60초 이내에 이루어져야 하며, 그렇지 않으면 변경 사항이 자동으로 되돌아갑니다

  • OPNsense 26.7 이상에서는 savepoint API가 없습니다: 쓰기 도구가 빈 revision을 반환하고 opn_confirm_changes는 status: "not_applicable"을 반환합니다. 이는 오류가 아니라 예상된 동작입니다 — 변경 사항은 이미 영구적으로 적용되었습니다

진단 명령

MCP 서버를 디버깅해야 하는 경우:

# Test API connectivity directly
curl -k -u "your-key:your-secret" https://your-opnsense-ip/api/core/firmware/status

# Run the server directly
python -m opnsense_mcp

# Run tests to verify installation
pytest -v

개발

# Clone and install dev dependencies
git clone https://github.com/lucamarien/opnsense-mcp-server
cd opnsense-mcp-server
pip install -e ".[dev]"

# Run all tests (no real OPNsense needed — all tests use mocked API)
pytest -v

# Full CI pipeline (lint, format, type check, security scan, tests)
make validate

# Individual checks
ruff check src/ tests/          # Lint (includes bandit security checks)
ruff format src/ tests/          # Format
mypy src/ --strict               # Type checking

모범 사례

일반적인 방화벽 구성 작업에 대한 도메인별 가이드:

  • WhatsApp 통화 방화벽 규칙 — URL 테이블 별칭과 범위 지정 규칙을 사용하여 기본 거부 방화벽에서 WhatsApp 음성/영상 통화 허용

이 가이드들은 실제 MCP 도구 사용 패턴을 보여주고 각 접근 방식의 보안 고려 사항을 설명합니다.

기여

자세한 지침은 CONTRIBUTING.md를 참조하세요. 주요 사항:

  1. 모든 테스트는 모의(mock) API 응답을 사용해야 합니다 — 실제 OPNsense에 연결하지 마세요

  2. 중복되는 도구 없음 — 각 도구는 고유한 목적이 있어야 합니다

  3. 명확한 docstring을 작성하세요 — 이는 AI가 도구 선택 시 참고하는 유일한 안내입니다

  4. 형식화된 문자열이 아닌 구조화된 데이터(dict)를 반환하세요

  5. 제출 전에 make validate를 실행하세요

라이선스

MIT

Install Server
A
license - permissive license
A
quality
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
5wRelease cycle
5Releases (12mo)
Commit activity
Issues opened vs closed

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Related MCP Servers

  • OPNsense MCP Server

    Pixelworlds
    A
    license
    Not graded
    quality
    F
    maintenance
    A modular MCP server that provides access to over 2,000 OPNsense firewall management methods through 88 specialized tools. It enables AI assistants to securely manage firewall rules, network interfaces, and system diagnostics using a type-safe TypeScript interface.
    370
    73
    MIT

  • OPNsense MCP Server

    gabrielion
    A
    license
    Not graded
    quality
    A
    maintenance
    This MCP server enables AI agents to inspect and modify an OPNsense firewall via natural language, using a compact set of generic tools and a resource registry to cover 96 CRUD operations.
    29
    AGPL 3.0

View all related MCP servers

Related MCP Connectors

  • royal-mcp

    Security-first WordPress MCP server. 129 tools for Claude, ChatGPT, Gemini. Free on wp.org.

  • secureflows-mcp

    MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.

  • microservices.sh

    MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/lucamarien/opnsense-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server