pfSense MCP Server
Enables natural language interaction with pfSense firewalls through GenAI applications.
pfSense Enhanced MCP Server
A Model Context Protocol (MCP) server for managing pfSense firewalls through Claude Desktop, Claude Code, and other MCP-compatible clients. Verified against the pfSense REST API v2 PHP source code for production accuracy.
Supported pfSense Versions
| pfSense Version | REST API Package | Status |
|---|---|---|
| pfSense CE 2.8.1 | v2.7.3 | Verified |
| pfSense Plus 25.11 | v2.7.3 | Verified |
| pfSense CE 2.8.0 | v2.6.0+ | Supported |
| pfSense Plus 24.11 | v2.6.0+ | Supported |
| pfSense CE 26.03 | Not yet available | Pending REST API package build |
Requires the pfSense REST API v2 package by jaredhendrickson13.
Quick Start
1. Install pfSense REST API Package
SSH into your pfSense box and install the package for your version:
# pfSense CE 2.8.1
pkg-static add https://github.com/pfrest/pfSense-pkg-RESTAPI/releases/latest/download/pfSense-2.8.1-pkg-RESTAPI.pkg
# pfSense Plus 25.11
pkg-static -C /dev/null add https://github.com/pfrest/pfSense-pkg-RESTAPI/releases/latest/download/pfSense-25.11-pkg-RESTAPI.pkg
Then in the pfSense web UI: System > REST API to enable it, and System > User Manager > [your user] to generate an API key.
2. Setup MCP Server
git clone https://github.com/gensecaihq/pfsense-mcp-server.git
cd pfsense-mcp-server
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your pfSense URL and API key
3. Configure Claude Desktop
Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"pfsense": {
"command": "python",
"args": ["-m", "src.main"],
"cwd": "/path/to/pfsense-mcp-server",
"env": {
"PFSENSE_URL": "https://your-pfsense.local",
"PFSENSE_API_KEY": "your-api-key",
"PFSENSE_VERSION": "CE_2_8_0",
"AUTH_METHOD": "api_key",
"VERIFY_SSL": "true"
}
}
}
}
4. Start the Server
# stdio mode (default — for Claude Desktop / Claude Code)
python -m src.main
# HTTP mode (for remote access, requires MCP_API_KEY for bearer auth)
python -m src.main -t streamable-http --port 3000
MCP Tools (41 total)
Firewall Rules (9 tools)
| Tool | Description |
|---|---|
search_firewall_rules | Search rules with filtering by interface, source IP, port, type, description |
find_blocked_rules | Find all block/reject rules |
create_firewall_rule_advanced | Create rule with position control and validation |
update_firewall_rule | Update an existing rule by ID |
delete_firewall_rule | Delete a rule by ID |
move_firewall_rule | Reorder a rule to a new position |
apply_firewall_changes | Explicitly trigger pf filter reload |
bulk_block_ips | Block multiple IPs with a single apply |
get_pf_rules | Read the compiled pf ruleset (/tmp/rules.debug) |
Aliases (5 tools)
| Tool | Description |
|---|---|
search_aliases | Search aliases by name, type, or contained IP |
create_alias | Create a new alias (host, network, port, url) |
update_alias | Update an existing alias |
delete_alias | Delete an alias |
manage_alias_addresses | Add or remove addresses from an alias |
NAT Port Forwards (4 tools)
| Tool | Description |
|---|---|
search_nat_port_forwards | Search port forward rules |
create_nat_port_forward | Create a port forward with validation |
update_nat_port_forward | Update a port forward |
delete_nat_port_forward | Delete a port forward |
DHCP (7 tools)
| Tool | Description |
|---|---|
search_dhcp_leases | Search active DHCP leases |
search_dhcp_static_mappings | Search static DHCP reservations |
create_dhcp_static_mapping | Create a static mapping |
update_dhcp_static_mapping | Update a static mapping |
delete_dhcp_static_mapping | Delete a static mapping |
get_dhcp_server_config | Get DHCP server configuration |
update_dhcp_server_config | Update DHCP server settings |
Services (2 tools)
| Tool | Description |
|---|---|
search_services | List services with status filtering |
control_service | Start, stop, or restart a service by name |
Logs & Monitoring (3 tools)
| Tool | Description |
|---|---|
get_firewall_log | Get firewall log entries (max 50 lines) |
analyze_blocked_traffic | Group blocked traffic by source IP with threat scoring |
search_logs_by_ip | Search logs for a specific IP address |
System (4 tools)
| Tool | Description |
|---|---|
system_status | Get CPU, memory, disk, and version info |
search_interfaces | Search network interfaces |
find_interfaces_by_status | Find interfaces by status (up/down) |
get_arp_table | Get ARP table (IP-to-MAC mappings) |
Utility (7 tools)
| Tool | Description |
|---|---|
follow_api_link | Follow a HATEOAS link |
enable_hateoas / disable_hateoas | Toggle HATEOAS link inclusion |
refresh_object_ids | Re-query endpoint to get fresh IDs |
find_object_by_field | Look up object by field value |
get_api_capabilities | Get REST API settings |
test_enhanced_connection | Test connection and feature availability |
API Endpoint Coverage
| Category | Endpoints | Operations |
|---|---|---|
| Firewall Rules | /firewall/rules, /firewall/rule, /firewall/apply | Full CRUD + apply |
| Aliases | /firewall/aliases, /firewall/alias | Full CRUD + append/remove |
| NAT | /firewall/nat/port_forwards, /firewall/nat/port_forward | Full CRUD |
| DHCP Leases | /status/dhcp_server/leases | Read |
| DHCP Static Mappings | /services/dhcp_server/static_mappings, /services/dhcp_server/static_mapping | Full CRUD |
| DHCP Server Config | /services/dhcp_servers, /services/dhcp_server | Read + Update |
| Services | /status/services, /status/service | Read + Control |
| Firewall Logs | /status/logs/firewall | Read (text-based filtering) |
| System Logs | /status/logs/system, /status/logs/dhcp, /status/logs/openvpn, /status/logs/auth | Read |
| System Status | /status/system | Read |
| Interfaces | /status/interfaces | Read |
| ARP Table | /diagnostics/arp_table | Read |
| Diagnostics | /diagnostics/command_prompt | Execute |
| API Settings | /system/restapi/settings | Read |
Not Yet Implemented
- Routing — static routes, gateways, gateway groups
- VPN — OpenVPN servers/clients, IPsec, WireGuard
- DNS — resolver/forwarder config, host overrides
- Certificates — CA, certificate, CSR management
- Users — user/group CRUD, LDAP/RADIUS
- NAT Outbound / 1:1 — outbound NAT rules
- Advanced — schedules, traffic shaper, virtual IPs
Architecture
src/
main.py Entry point (argparse, connection test, mcp.run())
server.py FastMCP instance + API client singleton
client.py HTTP client for pfSense REST API v2
models.py Enums, dataclasses (QueryFilter, SortOptions, etc.)
helpers.py Validation, pagination, safety guards
middleware.py Bearer auth middleware for HTTP transport
tools/
firewall.py 9 tools
aliases.py 5 tools
nat.py 4 tools
dhcp.py 7 tools
services.py 2 tools
logs.py 3 tools
system.py 4 tools
utility.py 7 tools
Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
PFSENSE_URL | Yes | https://pfsense.local | pfSense URL |
PFSENSE_API_KEY | Yes (for api_key auth) | — | REST API key |
AUTH_METHOD | No | api_key | api_key, basic, or jwt |
PFSENSE_VERSION | No | CE_2_8_0 | CE_2_8_0, CE_2_8_1, CE_26_03, PLUS_24_11, PLUS_25_11 |
VERIFY_SSL | No | true | Verify SSL certificates |
ENABLE_HATEOAS | No | false | Include HATEOAS links in responses |
LOG_LEVEL | No | INFO | DEBUG, INFO, WARNING, ERROR |
MCP_TRANSPORT | No | stdio | stdio or streamable-http |
MCP_HOST | No | 0.0.0.0 | Bind address for HTTP mode |
MCP_PORT | No | 3000 | Port for HTTP mode |
MCP_API_KEY | Required for HTTP mode | — | Bearer token for HTTP transport auth |
Docker
# Build
docker build -t pfsense-mcp .
# Run in stdio mode
docker run --rm -e PFSENSE_URL=https://pfsense.local -e PFSENSE_API_KEY=your-key pfsense-mcp
# Run in HTTP mode (docker-compose)
docker compose up
The docker-compose.yml runs in streamable-http mode on port 3000 with bearer auth.
Testing
# Run all 223 tests
python -m pytest tests/ -v
# With coverage
python -m pytest tests/ --cov=src --cov-report=term-missing
# Only tool tests
python -m pytest tests/tools/ -v
# Only client tests
python -m pytest tests/test_api_client.py -v
Safety Guards
- Page size capped at 200 — prevents pfSense PHP memory exhaustion
- Log lines capped at 50 — same reason
- Port format validation — rejects
"53 853"which crashes the pf compiler - IP validation — validates addresses before sending to API
- Log type allowlist — prevents path traversal via log endpoint
- Bearer auth required for HTTP transport mode (fail-closed)
- Control parameters in JSON body — verified against pfSense API PHP source
Known Limitations
- Firewall log API only exposes raw
textfield; per-field filtering is done client-side - HATEOAS toggle is a global API setting, not per-request (the tools toggle a local session flag)
- pfSense object IDs are non-persistent array indices that change after deletions
- Log retrieval is capped at 50 lines per request to prevent PHP memory exhaustion
Community & Contributions
We Need Your Help!
This MCP server has been verified against the pfSense REST API v2 PHP source code, but real-world testing across diverse pfSense environments is essential. Whether you're a pfSense veteran, Python developer, or GenAI enthusiast, there are many ways to contribute.
How You Can Help
Testing & Feedback
- Test with your pfSense setup and report what works (and what doesn't)
- Share use cases — tell us how you're using the MCP tools
- Performance feedback across different network sizes
Bug Reports & Issues
- Open an issue with detailed reproduction steps
- Suggest new MCP tools or API integrations
- Help improve documentation based on real-world usage
Code Contributions
- Add tools for missing endpoint categories (VPN, routing, DNS, certificates)
- Add support for pfSense packages (Snort, Suricata, HAProxy)
- Improve test coverage for edge cases
- Performance optimizations
Documentation
- Real-world example prompts that work well with Claude
- Integration guides for other MCP clients
- Video tutorials for setup and usage
Getting Started as a Contributor
- Fork the repository and create a feature branch
- Run the test suite:
python -m pytest tests/ -v - Update tests for any new features
- Submit a pull request with a clear description
Ideas for Contributions
High Priority
- VPN status and configuration tools (OpenVPN, IPsec, WireGuard)
- Routing and gateway management
- DNS resolver/forwarder configuration
- Certificate management
Medium Priority
- Support for pfSense packages (Snort, ntopng, FreeRADIUS)
- Multi-pfSense instance management
- GraphQL API integration
- Enhanced log parsing and analysis
Stay Connected
- GitHub Issues: Report bugs and request features
- Pull Requests: Contribute code and documentation
- Releases: Follow for updates
License
MIT License — see LICENSE for details.
Acknowledgments
- jaredhendrickson13 / pfrest for the pfSense REST API v2 package
- JeremiahChurch for the production-tested modular rewrite (PR #5, 217 tests)
- shawnpetersen for discovering the correct API v2 endpoint paths (PR #3)
- Netgate for pfSense
- FastMCP for the MCP framework
相關伺服器
Scout Monitoring MCP
贊助Put performance and error data directly in the hands of your AI assistant.
Alpha Vantage MCP Server
贊助Access financial market data: realtime & historical stock, ETF, options, forex, crypto, commodities, fundamentals, technical indicators, & more
Bonk MCP
Implements Solana blockchain functionality for the LetsBonk launchpad.
Jupyter MCP Server
Interact with Jupyter notebooks running in any JupyterLab environment, supporting real-time control and smart execution of notebook cells.
MCP-Inscription Server
Interact with Ordinals Inscriptions and display content from transactions.
Scientific Computation MCP
Provides tools for scientific computation, including tensor storage, linear algebra, vector calculus, and visualization.
openapi-to-mcp
Expose API endpoints as strongly typed tools from an OpenAPI specification. Supports OpenAPI 2.0/3.0 in JSON or YAML format, from local or remote files.
MCP Server
Automate data science stages using your own CSV data files.
symbolica-mcp
A scientific computing server for symbolic math, data analysis, and visualization using popular Python libraries like NumPy, SciPy, and Pandas.
MCP Expr Lang
MCP Expr-Lang provides a seamless integration between Claude AI and the powerful expr-lang expression evaluation engine.
Anubis
Embeds intelligent guidance into AI workflows to organize development and ensure quality.
CocoaPods Package README
Retrieve README files and package information from CocoaPods.