FortiGate MCP Server

개요

이것은 AI 어시스턴트가 FortiGate 방화벽을 관리할 수 있게 해주는 MCP(Model Context Protocol) 서버입니다 — 단일 랩 장비부터 수십 개의 고객, 사이트, 클러스터로 구성된 멀티 테넌트 환경까지.

대부분의 FortiGate 자동화 도구가 동시에 갖추지 못한 세 가지 핵심 아이디어를 기반으로 설계되었습니다:

1. 미리 보기 없이는 어떤 변경도 수행되지 않습니다. 모든 생성/수정/삭제 호출은 즉시 실행되는 대신 diff와 change_id를 반환합니다. 별도의 change_apply 호출이 실제로 변경을 실행하며, 실행 전에 라이브 상태의 드리프트(drift)를 다시 확인합니다. 신뢰할 수 있는 자동화라 할지라도 "그냥 실행" 모드는 존재하지 않습니다.

2. Claude는 실제 자격 증명을 볼 수 없습니다. 장비 비밀번호/API 토큰은 로컬의 비-MCP CLI(fortinet-mcp-cred)를 통해 OS 자격 증명 저장소(Windows Credential Manager / macOS Keychain / Linux Secret Service)에 직접 프로비저닝됩니다. MCP 도구 표면은 항상 불투명한 credential_id만 처리합니다.

3. 정책 CRUD뿐만 아니라 전체 수명 주기를 다룹니다. 장비 부트스트랩(DNS/NTP/syslog/SNMP/admin/HA), VDOM 멀티 테넌시, 인터페이스/존/DHCP, 라우팅, 방화벽 정책, VPN(IPsec + SSL), 보안/규정 준수 분석, 문서 생성까지 모두 일급 도구 네임스페이스로 제공됩니다 — 전체 도구 참조(115개 도구)를 참조하세요.

Related MCP server: FortiGate MCP Server

기능

전체 115개 도구의 목록은 docs/TOOLS.md를 참조하세요.

빠른 시작

git clone https://github.com/Serrinho02/fortigate-mcp-server.git
cd fortigate-mcp-server
uv sync

config/config.json을 생성합니다(레거시 단일 파일 장비 목록은 아래 설치의 인벤토리 시스템을 사용하는 경우 선택 사항입니다):

{ "fortigate": { "devices": {} } }

MCP 클라이언트(예: Claude Desktop)를 서버에 연결합니다:

{
  "mcpServers": {
    "fortigate": {
      "command": "/absolute/path/to/fortigate-mcp-server/.venv/bin/python",
      "args": ["-m", "src.fortigate_mcp.server"],
      "env": {
        "FORTIGATE_MCP_CONFIG": "/absolute/path/to/fortigate-mcp-server/config/config.json",
        "FORTINET_MCP_MODE": "full"
      }
    }
  }
}

그런 다음 Claude에서: 장비를 등록하고(inventory_register_device_pending), fortinet-mcp-cred set <credential_id>로 자격 증명을 로컬에 프로비저닝한 후, get_device_status를 호출합니다. 전체 설치 안내, Windows 경로, Docker 지침: docs/INSTALLATION.md. 개념 가이드 및 실제 예제: docs/USAGE.md.

아키텍처

7개 계층, 의존성은 한 방향으로만 흐릅니다:

flowchart TB
    Transport["MCP Tool Layer -- inventory.*, connection.*, policy/network/routing/vip.*, vpn.*, system.*, vdom.*, analysis.*, doc.*, fleet.*, intent.*, change.*"]
    Services["Service Layer -- one Service per capability, mode enforcement, error translation"]
    Domain["Domain / Analysis Engines -- pure functions: DiffEngine, policy analyzers, scoring"]
    Repo["Repository Layer -- inventory/change/snapshot persistence"]
    Adapters["Vendor Adapter Layer -- FortinetProductAdapter Protocol (the plugin boundary)"]
    Clients["Vendor API Client -- FortiOSRestClient (httpx, persistent per-device connection)"]
    Infra["Infra -- ConnectionManager, CredentialManager (keyring), SQLite/SQLAlchemy"]

    Transport --> Services
    Services --> Domain
    Services --> Repo
    Domain --> Repo
    Repo --> Adapters
    Adapters --> Clients
    Services -.uses.-> Infra

FortinetProductAdapter는 유일한 확장 경계입니다: 현재 FortiOSAdapter가 유일한 구현체이지만, 다른 Fortinet 제품을 추가하려면 동일한 Protocol에 대해 새 어댑터 하나만 작성하면 됩니다 — 그 위의 어떤 계층도 변경할 필요가 없습니다.

운영 모드

FORTINET_MCP_MODE로 설정합니다(기본값 full):

보안 모델

• 장비 자격 증명은 도구 인자로 사용되지 않으며 대화에 등장하지 않습니다. inventory_register_device_pending은 메타데이터(호스트, 이름, 고객, 사이트)만 수집하고 불투명한 credential_id를 발급합니다. 실제 비밀은 fortinet-mcp-cred set <credential_id>를 통해 로컬에서 한 번만 입력되며, OS 자격 증명 저장소에 직접 저장됩니다.

• connection_connect / 세션이 필요한 모든 도구는 해당 CLI 단계가 완료될 때까지 "credential not provisioned" 오류로 실패합니다 — MCP를 통해 비밀이 흐를 수 있는 우회 경로는 없습니다.

• 두 가지 문서화된 예외가 있으며, 둘 다 도구 설명에 명시되어 있습니다: IPsec 터널의 PSK(vpn_create_ipsec_tunnel)와 로컬 관리 계정의 비밀번호(system_create_admin)는 일반적인 도구 인자입니다. FortiOS 자체가 GET 시 이 값들을 절대 반환하지 않기 때문에, 값이 호출을 한 번 통과하지 않고서는 preview/diff를 수행할 방법이 없습니다.

알려진 제한 사항

• 선언적 "원하는 상태 적용" 도구가 없습니다. 의도적인 설계입니다 — 이 서버가 Terraform/Ansible 스타일의 apply 엔진을 소유하는 대신, Claude가 세분화된 도구들을 직접 조합합니다(intent.* 패턴 참조).

• Docker + 헤드리스 Linux: 자격 증명 관리자는 OS keyring 라이브러리를 래핑합니다. Secret Service 데몬이 없는 컨테이너/헤드리스 Linux 호스트에서는 keyrings.cryptfile 폴백이 필요합니다(기본적으로 연결되지 않음) — docs/INSTALLATION.md를 참조하세요. Windows/macOS/데스크톱 Linux의 네이티브 설치는 바로 작동합니다.

• SNMP: v1/v2c 커뮤니티만 지원됩니다. SNMPv3 사용자는 아직 없습니다.

• FortiManager/FortiWeb/기타 Fortinet 제품 어댑터는 아직 없습니다 — 어댑터 Protocol은 지원하지만 FortiOS 외에는 구현된 것이 없습니다.

• 모의 FortiOS REST API에 대한 실제 HTTP 트래픽 캡처로 엔드투엔드 검증을 완료했습니다. 실제 장비에서 문제가 발생하면 FortiOS 버전과 엔드포인트를 포함해 이슈를 열어주세요.

테스트

uv run pytest

548개의 테스트, 외부 의존성 불필요(전체 스위트에서 장비 상호작용은 HTTP 전송 계층에서 모의 처리됩니다).

기여

이슈와 PR을 환영합니다. 새 리소스 유형을 추가하는 경우 VPN 또는 시스템 구성 도메인이 추가된 방식을 참조하세요(services/vpn_service.py, services/system_service.py, services/change_dispatch.py) — 모든 새 변경 리소스는 동일한 adapter -> change_dispatch -> service -> MCP 도구 패턴을 따릅니다.

작성자

Nicola Serra가 구축하고 유지 관리합니다.

라이선스

MIT — LICENSE를 참조하세요.