FortiGate MCP Server

Descripción general

Este es un servidor MCP (Model Context Protocol) que permite que un asistente de IA administre firewalls FortiGate: desde un único dispositivo de laboratorio hasta un parque multi-tenant con docenas de clientes, sitios y clústeres.

Está construido sobre tres ideas que la mayoría de las herramientas de automatización de FortiGate no tienen las tres a la vez:

1. Nada muta sin una vista previa. Cada llamada de crear/actualizar/eliminar devuelve un diff y un change_id en lugar de ejecutarse inmediatamente. Una llamada separada, change_apply, es la que realmente lo ejecuta, y vuelve a comprobar el estado en vivo para detectar desviaciones antes de hacerlo. No existe un modo de "simple hazlo ya" de un solo paso, ni siquiera para automatización de confianza.

2. Claude nunca ve una credencial real. Las contraseñas y tokens de los dispositivos se aprovisionan mediante una CLI local y no MCP (fortinet-mcp-cred) directamente en el almacén de credenciales de tu sistema operativo (Windows Credential Manager / macOS Keychain / Linux Secret Service). La superficie de herramientas MCP solo maneja un credential_id opaco.

3. Cubre todo el ciclo de vida, no solo el CRUD de políticas. El arranque de dispositivos (DNS/NTP/syslog/SNMP/admin/HA), la multi-tenancy con VDOM, interfaces/zonas/DHCP, enrutamiento, políticas de firewall, VPN (IPsec + SSL), análisis de seguridad/cumplimiento y generación de documentación son espacios de herramientas de primera clase; consulta la Referencia de herramientas completa (115 herramientas).

Related MCP server: FortiGate MCP Server

Características

Consulta docs/TOOLS.md para obtener la lista completa y generada de las 115 herramientas.

Inicio rápido

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

Crea un archivo minimalista config/config.json (la lista de dispositivos heredada de un solo archivo es opcional cuando se usa el sistema de inventario de abajo representada; consulte Instalación):

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

Apelfa tu cliente MCP (a) al final Desktop) al servidor:

{
  "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"
      }
    }
  }
}

Luego, desde Claude: registra un dispositivo (inventory_register_device_pending), configura su credencial localmente con fort-inet-mcp-cred set <credential_id> y llama a get_device_status. Guía completa, rutas para Windows e instrucciones sobre Docker: docs/INSTALLATION.md. Guía conceptual y ejemplos de trabajo: docs/USAGE.md.

Arquitectura

Sistema de arquitectura de siete capas, flujo de dependencia en él se mueve en una sola dirección:

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 es el único límite de extensibilidad: hoy FortiOSAdapter es la única implementación, pero añadir otro producto Fortinet significa escribir un nuevo adaptador con el mismo Protocol; nada por encima de esa capa cambia.

Modos de funcionamiento

Se han mediante FORTINET_MCP_MODE (por defecto full):

Modelo de seguridad

• Las credenciales del dispositivo nunca son un argumento de una conversación. inventory_register_device_pending solo recolecta metadatos (host, nombre, cliente, sitio de direcciones) y emite un credential_id opaco; el secreto real se introduces una vez, localmente, con fortinet-mcp-cred set <credentials_id> directamente en el almacén de credenciales del sistema operativo.

• connection_connect / cualquier herramienta visual necesite una sesión en vivo fallará con un error claro "no se ha aprovisionado la credencial" hasta que se complete ese paso de CLI; no hay ningún fallback que pueda permitir que un secreto fluya a los MCP.

• Dos excepciones documentadas, ambas señaladas directamente en la descripción de sus herramientas: la cabina IPsec del túnel (vpn_create_ipsec_tunnel) y la contraseña de una cuenta de administrador (system_create_admin) son argumentos de herramienta correctos, porque FortiOS no las devuelve nunca en GET, y no hay manera de previsualizarlas o diff sin la vez.

Limitaciones conocidas

• No hay herramienta declarativa "aplicar este estado deseado". Por diseño, Claude compone por sí mismo las herramientas granulares (ver intent.* para el patrón), en lugar de que este servidor tenga un motor de aplicación de estilo Terraform/Ansible.

• Docker + Linux headless: el gestor de credenciales envuelve la librería keyring del SO. En un sistema contenedor/headless Linux sin demonio Secret Service, necesitas usar el fallback keyring-cryptfile (no habilitado) por defecto; ver docs/INSTALLATION.md. La instalación nativa en Windows/macOS/escritorio Linux funciona de fábrica.

• SNMP: solo se admiten comunidades v1/v2c; no hay aún ruedas sino.

• Sin adaptadores para los productos Fortinet de FortiManager/FortiWeb/otros aún: el protocolo de adaptador lo admite, pero nada más está implementado fuera de FortiOS.

• Verificada de extremo a extremo con tráfico HTTP real capturado contra una API REST simulada de FortiOS; si te encuentras con un comportamiento de un dispositivo real, abre un issue con la versión de FortiOS y el endpoint.

Tests

uv run pytest

548 tests, without dependencies requiring external dependencies (device interaction is mocked at the HTTP transport level for the entire suite).

Contribuciones

Son bienvenidos problemas y los PR. Si estás añadiendo un nuevo tipo de recurso, mira cómo se añadieron los dominios de VPN o de configuración del sistema (services/vpn_service.py, services/system_service.py, services/change_dispatch.py): cada nuevo recurso mutante sigue el mismo patrón de adaptador -> change_dispatch -> service -> MCP.

Autor

Creado y mantenido por Nicola Serra.

Licencia

MIT: consulta LICENSE.