Skip to main content
Glama

firegex-mcp

MCP server that exposes Firegex — a CTF regex/proxy firewall — to LLM tooling like Claude Desktop or Claude Code.

Features

  • 49 tools across system, nfregex (kernel-side PCRE2 filter), nfproxy (Python inline proxy), firewall (nftables rules), and porthijack (port redirection).

  • Auto-managed JWT lifecycle: log in on first use, transparently re-login on 401 / secret rotation, single asyncio.Lock to avoid login storms.

  • Plain-text regex on the tool boundary; base64 is handled inside the client.

  • Two ways to push nfproxy Python filters: inline code: str or local path: str (≤ 1 MiB).

  • Pure async httpx client + pydantic v2 DTOs.

  • stdio transport — drop into Claude Desktop or Claude Code as a subprocess.

Related MCP server: Globalping

Install

uvx firegex-mcp        # ephemeral, recommended
# or
pip install firegex-mcp

Configure

All settings are env vars with the FIREGEX_MCP_ prefix:

Env var

Default

Description

FIREGEX_MCP_BASE_URL

http://localhost:4444

Firegex base URL

FIREGEX_MCP_PASSWORD

(required)

Used at /api/login

FIREGEX_MCP_TIMEOUT_SECONDS

30

HTTP request timeout

FIREGEX_MCP_LOG_LEVEL

INFO

DEBUG/INFO/WARNING/ERROR/CRITICAL

See .env.example for a starter template.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %AppData%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "firegex": {
      "command": "uvx",
      "args": ["firegex-mcp"],
      "env": {
        "FIREGEX_MCP_BASE_URL": "http://localhost:4444",
        "FIREGEX_MCP_PASSWORD": "..."
      }
    }
  }
}

Restart Claude Desktop fully (Cmd+Q / tray → Quit), then look for the connector under the + menu.

Claude Code

claude mcp add firegex uvx firegex-mcp --env FIREGEX_MCP_PASSWORD=...

Tools

Grouped by Firegex module. See the design spec for the full catalogue.

  • system (6): get_firegex_status, set_password, change_password, list_interfaces, reset_firegex, login_probe.

  • nfregex (15): services CRUD + regex CRUD/toggle + Prometheus metrics.

  • nfproxy (14): services CRUD + pyfilter toggle + get_pyfilter_code, set_pyfilter_code, set_pyfilter_code_from_file.

  • firewall (6): get_firewall_settings, set_firewall_settings, enable_firewall, disable_firewall, list_firewall_rules, replace_firewall_rules.

  • porthijack (8): services CRUD + rename_phj_service + change_phj_destination.

Development

git clone https://github.com/umbra2728/firegex-mcp
cd firegex-mcp
uv sync --dev
uv run pytest
uv run ruff check src tests
uv run mypy src

Manual smoke test against a real Firegex instance:

# in the firegex repo
python3 run.py start --prebuilt
# back here
FIREGEX_MCP_PASSWORD=test uv run mcp dev src/firegex_mcp/server.py

This opens the MCP Inspector in your browser; you can call every tool by hand.

Releasing

This package ships to PyPI via Trusted Publishing. The workflow runs on any v*.*.* tag.

  1. Bump version in pyproject.toml.

  2. Add a ## [X.Y.Z] - YYYY-MM-DD section to CHANGELOG.md.

  3. Commit, tag, push:

git commit -am "Release vX.Y.Z"
git tag vX.Y.Z
git push --tags

One-time setup (not in repo state):

  • PyPI → Account settings → Add a pending publisher with repo umbra2728/firegex-mcp, workflow release.yml, environment pypi.

  • GitHub → repo → Settings → Environments → create pypi.

  • packmate-mcp — sibling MCP server for Packmate (CTF network traffic analyzer).

  • ad-ctf-toolkit — Claude Code plugin that combines firegex-mcp and packmate-mcp with skills and sub-agents for Attack/Defense CTF rounds.

Contact

Questions, suggestions, bug reports, or anything else — reach out:

License

MIT — see LICENSE.

Available Tools

49 tools
add_nfproxy_serviceC

Register a new nfproxy service. proto is 'tcp' or 'http'.

Inputs: name (required), port (required), proto (required), ip_int (required), +1 more. Returns: object

add_nfregex_serviceB

Register a new nfregex service.

proto must be 'tcp' or 'udp'. ip_int is the bind interface (IPv4/IPv6 literal, '0.0.0.0' for all). fail_open=True means traffic flows when the regex engine cannot start.

Inputs: name (required), port (required), proto (required), ip_int (required), +1 more. Returns: object

add_phj_serviceA

Add a porthijack rule.

ip_src is the inbound bind interface; ip_dst is the new destination. public_port is what clients connect to; traffic is rewritten to ip_dst:proxy_port. Use this to plug your own proxy in front of a service.

Inputs: name (required), public_port (required), proxy_port (required), proto (required), +2 more. Returns: object

add_regexB

Add a PCRE2 regex to a service.

regex is plain text (the client base64-encodes for the wire). mode: 'C' = client→server only, 'S' = server→client only, 'B' = both.

Inputs: service_id (required), regex (required), mode (required), is_case_sensitive (required), +1 more. Returns: object

change_passwordA

Change the Firegex password (status == 'run' only).

expire=True rotates the server JWT secret, invalidating all current sessions; the MCP client transparently re-logs in on the next call.

Inputs: password (required), expire. Returns: object

change_phj_destinationB

Repoint an existing porthijack rule to a new ip_dst:proxy_port.

Inputs: service_id (required), ip_dst (required), proxy_port (required). Returns: object

delete_nfproxy_serviceB

Delete a service and its filter code.

Inputs: service_id (required). Returns: object

delete_nfregex_serviceC

Delete a service and all its regexes.

Inputs: service_id (required). Returns: object

delete_phj_serviceC

Remove a porthijack rule permanently.

Inputs: service_id (required). Returns: object

delete_regexC

Permanently delete a regex.

Inputs: regex_id (required). Returns: object

disable_firewallA

Deactivate the nftables firewall ruleset (all rules unloaded).

Inputs: no named parameters. Returns: object

disable_pyfilterB

Disable a single pyfilter by name.

Inputs: service_id (required), filter_name (required). Returns: object

disable_regexA

Disable a regex (kept in DB, not applied).

Inputs: regex_id (required). Returns: object

enable_firewallA

Activate the nftables firewall ruleset.

Inputs: no named parameters. Returns: object

enable_pyfilterC

Enable a single pyfilter by name.

Inputs: service_id (required), filter_name (required). Returns: object

enable_regexA

Enable a previously-disabled regex without deleting it.

Inputs: regex_id (required). Returns: object

get_firegex_statusA

Return Firegex global status: init (no password yet) or run.

Also reports the API version and whether the current session is logged in.

Inputs: no named parameters. Returns: status, loggined, version

get_firewall_settingsA

Read the firewall meta-settings (loopback, established, ICMP, mDNS, ...).

Inputs: no named parameters. Returns: keep_rules, allow_loopback, allow_established, allow_icmp, +4 more

get_nfproxy_serviceC

Get a single nfproxy service by id.

Inputs: service_id (required). Returns: service_id, status, port, name, +6 more

get_nfregex_metricsA

Prometheus-format metrics for the nfregex module (blocked_packets, active).

Inputs: no named parameters. Returns: result

get_nfregex_serviceA

Get a single nfregex service by id.

Inputs: service_id (required). Returns: service_id, status, port, name, +5 more

get_phj_serviceB

Get a single porthijack rule.

Inputs: service_id (required). Returns: service_id, active, public_port, proxy_port, +4 more

get_pyfilter_codeA

Read the current Python filter source for a service (empty string if unset).

Inputs: service_id (required). Returns: result

get_regexA

Get a single regex by numeric id.

Inputs: regex_id (required). Returns: Regex row. `regex` is exposed as plain text; on the wire it's base64.

list_firewall_rulesB

Return current rules, policy ('accept'/'drop'/'reject'), and enabled state.

Inputs: no named parameters. Returns: rules, policy, enabled

list_interfacesA

List the IPv4 and IPv6 interfaces visible to Firegex.

Inputs: no named parameters. Returns: result

list_nfproxy_servicesA

List nfproxy services (Python-pluggable inline proxy for TCP/HTTP).

Inputs: no named parameters. Returns: result

list_nfregex_servicesA

List nfregex services (one Firegex service = one TCP/UDP port being filtered).

Inputs: no named parameters. Returns: result

list_phj_servicesA

List port-hijack rules (each redirects public_port → proxy_port on ip_dst).

Inputs: no named parameters. Returns: result

list_pyfiltersC

List Python filters discovered in the service code.

Inputs: service_id (required). Returns: result

list_regexesB

List regexes attached to a service. The regex field is plain text.

Inputs: service_id (required). Returns: result

login_probeA

Force the auth lifecycle and return the (now-authenticated) status.

Useful for verifying connectivity, credentials, and that the server has been initialised. Raises FiregexNotInitializedError when status='init'.

Inputs: no named parameters. Returns: object

rename_nfproxy_serviceD

Rename a service.

Inputs: service_id (required), name (required). Returns: object

rename_nfregex_serviceD

Rename a service.

Inputs: service_id (required), name (required). Returns: object

rename_phj_serviceC

Rename a porthijack rule.

Inputs: service_id (required), name (required). Returns: object

replace_firewall_rulesA

Atomically replace the entire rule list.

Firegex performs DELETE FROM rules; INSERT ... in one transaction — there is no per-rule CRUD. Read with list_firewall_rules, mutate, then write back.

Inputs: policy (required), rules (required). Returns: object

reset_firegexA

Reset Firegex's nftables state.

DANGEROUS when delete=True: this also wipes all SQLite databases (services, regexes, rules). Use delete=False to only flush nftables rules and reload the saved config.

Inputs: delete (required). Returns: object

set_firewall_settingsB

Replace the firewall settings. All fields are required (no partial update).

Inputs: keep_rules (required), allow_loopback (required), allow_established (required), allow_icmp (required), +4 more. Returns: object

set_passwordA

Set the initial Firegex password. Only valid while status == 'init'.

Inputs: password (required). Returns: object

set_pyfilter_codeC

Replace the Python filter source for a service.

The code must import pyfilter from firegex.nfproxy and decorate one or more handlers. Firegex compiles the code server-side and returns 400 on syntax/import errors.

Inputs: service_id (required), code (required). Returns: object

set_pyfilter_code_from_fileA

Load Python filter code from a local file and push it to Firegex.

The path is read on the machine running the MCP server. UTF-8 only. Files larger than 1 MiB are rejected.

Inputs: service_id (required), path (required). Returns: object

start_nfproxy_serviceC

Start the nfproxy engine.

Inputs: service_id (required). Returns: object

start_nfregex_serviceC

Start the nfregex engine for this service.

Inputs: service_id (required). Returns: object

start_phj_serviceC

Activate a porthijack rule.

Inputs: service_id (required). Returns: object

stop_nfproxy_serviceC

Stop the nfproxy engine.

Inputs: service_id (required). Returns: object

stop_nfregex_serviceB

Stop the nfregex engine (traffic flows through unfiltered).

Inputs: service_id (required). Returns: object

stop_phj_serviceB

Deactivate a porthijack rule (traffic is no longer redirected).

Inputs: service_id (required). Returns: object

update_nfproxy_service_settingsB

Change settings of an existing nfproxy service (causes restart).

Inputs: service_id (required), port, ip_int, fail_open. Returns: object

update_nfregex_service_settingsB

Change service settings (causes restart). Only provided fields are updated.

Inputs: service_id (required), port, proto, ip_int, +1 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 49 tools

    Disambiguation5/5

    Every tool targets a distinct resource (nfproxy, nfregex, phj, firewall, pyfilter, regex, auth) with clear prefixes and specific actions. Overlap is minimal and descriptions clarify any ambiguity.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (e.g., add_nfproxy_service, delete_regex). Even varied verbs (start, stop, enable, disable) are uniformly applied across resource types.

    Tool Count4/5

    With 49 tools covering multiple subsystems, the count is high but justified by the breadth of Firegex's domain. Each tool serves a distinct purpose, and no tool seems superfluous.

    Completeness5/5

    The surface covers full CRUD and lifecycle operations for all main resource types: services, regexes, firewall rules, pyfilters, and auth. Missing operations like per-rule firewall CRUD are replaced by atomic replace, which is by design.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers