security-first MCP server for pfSense

Solo lectura por diseño hoy; ESCRITURA está escalonada detrás de una arquitectura de seguridad explícita

Documentación

pfsense-mcp-server

Acceso seguro y con privilegios mínimos a pfSense para asistentes de IA. Servidor MCP que brinda a un asistente de IA visibilidad de solo lectura, fuertemente tipada, sobre un solo dispositivo pfSense — sistema, red, firewall, DHCP, DNS, VPN, certificados y diagnósticos — sin acceso directo a shell, sin una superficie de scripting no auditada, ni ninguna forma de cambiar el dispositivo por accidente.

Lo construí porque quería asistencia de IA para pfSense sin darle a un LLM la capacidad de desconectar accidentalmente mi propia red — un firewall merece un estándar de seguridad más alto que "el modelo probablemente no hará un cambio malo". Consulta Por qué existe este proyecto para conocer el razonamiento completo.

Qué hace

97 herramientas: 95 herramientas READ de pfSense + 2 herramientas de guía de documentación. Cubre aproximadamente el 90% de la superficie READ útil de la API REST de pfSense. Cada herramienta está fuertemente tipada (Pydantic) — sin paso directo de JSON sin tipo.
0 herramientas WRITE por defecto. Existe una ruta de cambio protegido completamente construida y verificada dos veces en vivo, pero requiere una aceptación explícita — consulta Niveles de seguridad a continuación.
Pregúntale cosas como: "Lista mis VLANs y en qué interfaz va cada una," "¿Mi gateway WAN está activo ahora mismo?", "¿Qué certificados expiran pronto?", "¿Qué concesiones DHCP están activas en la LAN?" — cada pregunta se asigna a una herramienta tipada y limitada por capacidad.

Inicio rápido

pipx install pfsense-mcp-server
pfsense-mcp-security setup

(Si llegaste aquí desde el cuadro genérico "pip install" de PyPI arriba — ese es el encabezado fijo de la página de PyPI, no la recomendación de este proyecto. Usa el comando pipx que se muestra aquí en su lugar.)

¿Aún no tienes pipx? sudo apt install pipx && pipx ensurepath en Debian/Ubuntu (vuelve a abrir tu terminal después) — consulta Instalación para otras plataformas y una alternativa simple de entorno virtual. Un pip install a nivel de sistema no es deliberadamente la ruta recomendada: en Debian/Ubuntu moderno se rechaza directamente (PEP 668), e incluso donde no se rechaza, arriesga tocar paquetes de los que tu propio sistema operativo depende.

El asistente de configuración hace algunas preguntas en lenguaje natural — la dirección de tu firewall, si permitir solo lectura o cambios protegidos, cómo verificar la conexión — y luego imprime la configuración exacta para pegar en tu cliente MCP. No es necesario escribir ni editar nada a mano. ¿Prefieres configurar manualmente o quieres el recorrido completo paso a paso? Consulta Primeros pasos.

Una vez que tu cliente esté conectado y muestre 97 herramientas disponibles, prueba una de las preguntas de Qué hace arriba.

Niveles de seguridad

Elige el nivel que coincida con lo que necesitas — puedes cambiarlo más tarde ejecutando setup nuevamente.

Nivel	Qué significa	Para quién es
Solo lectura (predeterminado, recomendado)	La IA puede inspeccionar pfSense — estado, configuración, diagnósticos — pero no puede cambiar nada.	Casi todos. Esta es la opción más segura y cubre la gran mayoría del trabajo útil de pfSense asistido por IA.
Cambios protegidos	Agrega exactamente una capacidad (editar la descripción de un alias de firewall) detrás de una autorización firmada criptográficamente y un paso de confirmación separado.	Usuarios avanzados que tienen una razón específica y deliberada para permitir que la IA haga un cambio estrecho y auditable.
Cambios protegidos por hardware	Todo lo de Cambios protegidos, más un testigo externo respaldado por TPM que debe estar de acuerdo de forma independiente antes de que un cambio se considere verificado.	Operadores conscientes de la seguridad que quieren protección anti-reversión además de lo anterior.

Ningún nivel escala silenciosamente a otro, y nada por encima de solo lectura es alcanzable a menos que lo aceptes explícitamente durante la configuración. Los mecanismos internos exactos — resúmenes de plan, tokens de autorización, el ejecutor de mutación sellado, estado del testigo — están documentados en su totalidad para usuarios avanzados y auditores en el Modelo de seguridad.

Arquitectura de un vistazo

AI client (Claude, Codex, ...)
  │  MCP over stdio
  ▼
pfsense-mcp-server
  │  one typed method call, GET-only
  ▼
pfSense's pfREST API
  │
  ▼
pfSense appliance

Cada una de las 95 herramientas READ toma esta ruta exacta, sin excepciones — aplicado mecánicamente en tiempo de compilación, no solo por convención (una verificación de make validate requiere exactamente una llamada de cliente tipada por herramienta READ, evitando estructuralmente un desajuste herramienta/endpoint).

READ trust path: AI/MCP client through stdio, an explicitly registered MCP tool, capability/profile gate, least-privilege mapping, one fixed typed client method, a GET-only pfREST call, the pfSense appliance, a typed model boundary excluding secret fields, to a safe MCP result

La ruta de cambio protegido (construida, no alcanzable por defecto)

Existe una ruta completamente construida y verificada dos veces en vivo para exactamente una operación de cambio protegido (el campo de descripción de un alias de firewall), pero permanece inalcanzable a menos que la aceptes explícitamente durante la configuración: write_protected debe seleccionarse, una firma Ed25519 fuera del host para la cual el servidor en ejecución nunca tiene la clave debe autorizarla, y una autoridad de confirmación separada debe confirmarla. Consulta el asistente de configuración de seguridad y el modelo de seguridad para conocer exactamente qué requiere y qué no hace por defecto.

Consulta la página completa de diagramas de arquitectura para el detalle puerta por puerta detrás de ambos diagramas.

Qué obtienes

Categoría	Herramientas	Ejemplos
Sistema	26	hostname, DNS, versión, paquetes, configuración de API REST, diagnósticos
VPN	17	IPsec, OpenVPN, estado/config de WireGuard, CARP
Firewall	15	reglas, alias, estados, NAT, horarios, IPs virtuales, modeladores de tráfico
DNS	7	configuración del resolver, anulaciones, listas de acceso
Interfaces	9	estado, VLANs, grupos, puentes, LAGG
DHCP	7	servidores, asignaciones estáticas, concesiones, relay
Enrutamiento / Gateways	6	gateways, estado de gateway, rutas estáticas
Certificados / PKI	3	certificados, autoridades certificadoras, CRLs
Usuarios / Identidades API	3	usuarios locales, grupos de usuarios, claves API
Servicios / Monitoreo	2	estado de servicios, FreeRADIUS EAP

Referencia completa por herramienta, parámetros y procedencia: Referencia de herramientas MCP · Referencia de herramientas y guía.

Conecta tu cliente MCP

Para Claude Desktop y Codex CLI / ChatGPT desktop, una vez que la configuración de tu servidor funcione, genera el bloque de configuración exacto del cliente automáticamente:

pfsense-mcp-security setup write-client-config \
  --client claude-desktop --config-path /absolute/path/to/claude_desktop_config.json \
  --capability-posture read_only --anchor-assurance none

Esto previsualiza el cambio y pide confirmación explícita antes de escribir cualquier cosa — nunca sobrescribe silenciosamente una configuración existente. Cada otro cliente compatible — Claude Code, Cursor, VS Code, Continue y cualquier otro cliente compatible con MCP — tiene su propia guía lista para copiar y pegar en lugar de un generador. Guías listas por cliente — examples/README.md. Detalle completo: Conecta tu cliente MCP.

Requisitos

Python 3.11, 3.12 o 3.13.
pfSense con el paquete REST API (pfrest/pfSense-pkg-RESTAPI, API v2) instalado y habilitado.

Consulta Compatibilidad para saber exactamente qué ediciones/versiones de pfSense están verificadas directamente vs. simplemente se espera que funcionen.

Documentación

Primeros pasos Instalación · Asistente de configuración de seguridad · Conecta tu cliente MCP

Uso del servidor Referencia de herramientas MCP · Referencia de herramientas y guía · Referencia de configuración

Seguridad Modelo de seguridad · Modelo de amenazas · Arquitectura de seguridad Nivel 1

Referencia Compatibilidad · Diagramas de arquitectura · Hoja de ruta pública

Desarrollador / colaborador Decisiones de arquitectura · Contribuciones · Soporte · Política de seguridad

Estado de la versión

v0.9.0 es la línea base de producción inmutable, publicada en PyPI — 95 herramientas READ de pfSense + 2 herramientas de guía de documentación, 0 herramientas WRITE. pfsense_get_api_guidance cubre el paquete pfREST mantenido por la comunidad (pfSense-pkg-RESTAPI, documentado en pfrest.org), mantenido estructuralmente separado de pfsense_get_official_guidance (documentación del producto Netgate) — nunca mezclado. La evidencia está explícitamente etiquetada por procedencia (PROJECT_AUTHORED / PFREST_UPSTREAM / LIVE_APPLIANCE_SCHEMA / OFFICIAL_NETGATE); la documentación es datos, nunca autoridad. Consulta la entrada de [0.9.0] de CHANGELOG.md y docs/ACCEPTANCE_v0.9.0.md para la evidencia completa e independientemente verificada — cada etiqueta de versión anterior, GitHub Release y artefacto de PyPI permanece intacto como un registro histórico preciso.

Contribuciones

Las contribuciones son bienvenidas dentro de los límites documentados de seguridad y aprobación. Lee CONTRIBUTING.md antes de abrir un cambio.

Licencia

Licenciado bajo la Licencia MIT.

pfSense® es una marca registrada de Electric Sheep Fencing, LLC, licenciada exclusivamente a Rubicon Communications, LLC d/b/a Netgate. Este proyecto es una herramienta independiente construida por la comunidad. No está afiliado, respaldado ni patrocinado por Electric Sheep Fencing, LLC ni Netgate.