# io.github.martimy/batfish-q-mcp (pypi · batfish-q-mcp)

An MCP server exposing Batfish tools so AI assistants can query network configs in plain language.

- Trust score: 69/100 (medium)
- Change this week: +4
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-11-21

## Components

- pypi · `batfish-q-mcp`: 69/100 (this document), [markdown](https://verifymcp.io/servers/martimy-batfish-q-mcp/batfish-q-mcp.md), [page](https://verifymcp.io/servers/martimy-batfish-q-mcp/batfish-q-mcp)

## Channel facts

- Registry: `pypi`
- Package: `batfish-q-mcp`
- Version: `0.2.0`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-11-21.

- **Supply Chain Security**: 100/100
  - No malware found by supply-chain analysis.
  - No known CVEs affecting this package version or its production dependencies.
  - Runs setuptools.build_meta at install time, a recognised build step with no custom scripting around it.
  - 2 of 34 dependencies flagged as unhealthy.
- **Provenance & Transparency**: 45/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (Apache-2.0).
  - Actively maintained (last published 9 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 54/100
  - AI-judged instruction clarity (good).
  - Context-footprint check failed: tool/resource definitions use about 3829 tokens (~319/item across 12 items; 12 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 40/100
  - Stability observed for 12 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 71/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 0% of tool parameters carry a description.
  - Structured output schemas are declared (100% of tools); any adoption earns full credit.
- **Tool Safety**: 75/100
  - No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.
  - 0 of 1 tool(s) whose name or description implies an irreversible operation declare an MCP destructiveHint annotation; "batfish_delete_snapshot" implies "delete" and declares no destructiveHint at all, which the MCP spec reads as destructive by default.
  - An AI judge read all 13 captured unit(s) of tool text and found none that tries to manipulate the model reading it.
- **Capabilities**: 100/100
  - Implements a current MCP spec version (2026-07-28).

## Install

### How do I install the io.github.martimy/batfish-q-mcp server?

io.github.martimy/batfish-q-mcp runs locally as a PyPI package, launched with uvx batfish-q-mcp. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation.

### Claude

```bash
claude mcp add martimy-batfish-q-mcp -- uvx batfish-q-mcp
```

### Cursor

```json
{
  "mcpServers": {
    "martimy-batfish-q-mcp": {
      "command": "uvx",
      "args": [
        "batfish-q-mcp"
      ]
    }
  }
}
```

### VS Code

```json
{
  "servers": {
    "martimy-batfish-q-mcp": {
      "command": "uvx",
      "args": [
        "batfish-q-mcp"
      ]
    }
  }
}
```

### Codex

```bash
codex mcp add martimy-batfish-q-mcp -- uvx batfish-q-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "martimy-batfish-q-mcp": {
      "type": "local",
      "command": [
        "uvx",
        "batfish-q-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add martimy-batfish-q-mcp --command uvx --arg batfish-q-mcp
```

### Hermes

```yaml
mcp_servers:
  martimy-batfish-q-mcp:
    command: "uvx"
    args: ["batfish-q-mcp"]
```

### Netclaw

```json
{
  "McpServers": {
    "martimy-batfish-q-mcp": {
      "Transport": "stdio",
      "Command": "uvx",
      "Arguments": [
        "batfish-q-mcp"
      ]
    }
  }
}
```

### Vellum

```bash
assistant mcp add martimy-batfish-q-mcp -t stdio -c uvx -a batfish-q-mcp
```

### Other

```json
{
  "mcpServers": {
    "martimy-batfish-q-mcp": {
      "command": "uvx",
      "args": [
        "batfish-q-mcp"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-11-21 (score 69, +16)

- [security improvement] Malware scan: unverified → pass

### 2026-11-20 (score 53, −15)

- [security regression] Malware scan: pass → unverified

### 2026-11-19 (score 68, +1)

No change was recorded against any check on this day. Stability & Change Management went from 30 to 33. That category is still filling its 30-day observation window: 9 days of observed history at the previous scan, 10 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-11-18 (score 67, +15)

- [security improvement] Malware scan: unverified → pass

### 2026-11-17 (score 52, −14)

- [security regression] Malware scan: pass → unverified

### 2026-11-15 (score 66, +1)

No change was recorded against any check on this day. Stability & Change Management went from 17 to 20. That category is still filling its 30-day observation window: 5 days of observed history at the previous scan, 6 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-11-13 (score 65, +16)

- [security improvement] Malware scan: unverified → pass

### 2026-11-12 (score 49, −17)

- [security regression] Malware scan: pass → unverified
- [functional regression] Schema quality: 151 → 319
- [functional improvement] Stability: unverified → 0.10
- [functional] Destructive annotations: pass → 0
- [functional] Package version: 0.1.0 → 0.2.0

## MCP tools (12)

### `batfish_find_questions` (~192 tokens)

Batfish Find Questions

Find catalog questions from a plain-language query.

\``query`` is the user's own wording, e.g. ``"standby gateway"``,
\``"traffic going in circles"``, or ``"which firewall rule is blocking"``.
It is matched against question names, descriptions, categories, tags,
synonyms, input names/descriptions/allowed values, and output columns.

Returns ``{query, count, total_matches, results}`` where each result is
\``{fun, name, category, description, tags, synonyms,
supports_differential, differential_only, score, matched_on}``. Results are
ranked by relevance and capped at ``limit`` (default 5).

Use ``batfish_get_question(fun)`` for full input/output details. This tool
uses checked-in metadata and does not contact Batfish.

Input parameters:

- `limit` (integer)
- `query` (string, required)

### `batfish_list_questions` (~258 tokens)

Batfish List Questions

List Batfish questions from the curated catalog.

Returns one dict per question:
\``{category, category_description, fun, name, description, tags,
synonyms, supports_differential, differential_only, output_columns,
inputs, type?}``.

\- ``description`` is a one-line summary; ``tags`` are Batfish's tags;
  \``synonyms`` are plain-language search terms.
\- ``output_columns`` lists only column names; call
  \``batfish_get_question`` for their types and descriptions.
\- Each input is ``{name, type, required, hint?, fields?, placeholder?,
  example?}``. ``required`` is true when the input must be supplied
  (not optional and has no default).
\- ``supports_differential`` is true when the question accepts a
  \``reference_snapshot``. ``differential_only`` marks the two questions
  (``compareFilters`` and ``differentialReachability``) that can only be
  run differentially; ``type`` is retained on those entries.

Pass a category name to filter; omit it for the full catalog. This tool
uses checked-in metadata and does not contact Batfish.

Input parameters:

- `category`

Output parameters:

- `result` (array)

### `batfish_get_question` (~229 tokens)

Batfish Get Question

Return full metadata for one question, including output columns.

\``fun`` is a catalog question name (see ``batfish_list_questions``).

Returns ``{category, category_description, fun, name, description,
long_description, tags, synonyms, supports_differential,
differential_only, output_columns, inputs, type?}``:

\- ``output_columns`` is a list of ``{name, type, description}`` objects
  describing the answer table.
\- each input includes its catalog ``type`` and ``required`` flag plus
  template details when available: ``description``, ``display_name``,
  \``default``, ``allowed_values`` (strings, or ``{value, description}``
  objects), ``field_specs`` for structured values, and ``min_length``.
\- ``TYPE_HINTS`` add ``hint``/``fields``/``placeholder``/``example`` for
  complex values such as HeaderConstraints.

Raises ``ValueError`` for an unknown ``fun``, listing the known names.

Input parameters:

- `fun` (string, required)

### `batfish_list_snapshots` (~54 tokens)

Batfish List Snapshots

List snapshots of a Batfish network.

If ``network`` is given, the session is pointed at it first
(``set_network``); otherwise the session's current network is used.

Input parameters:

- `network`

Output parameters:

- `result` (array)

### `batfish_delete_snapshot` (~88 tokens)

Batfish Delete Snapshot

Delete a Batfish snapshot.

\- ``name``: the snapshot name to delete (sanitized with
  \``safe_snapshot_name``).
\- ``network``: the network the snapshot lives in; if given, the
  session is pointed at it first.

Returns ``{name}`` — the name that was deleted.

Input parameters:

- `name` (string, required)
- `network`

### `batfish_upload_snapshot` (~131 tokens)

Batfish Upload Snapshot

Upload a Batfish snapshot zip, base64-encoded.

The name is sanitized with ``safe_snapshot_name`` (Batfish allows only
letters, digits, '-' and '_'). Unless ``overwrite`` is true, an
existing snapshot of that name is kept and a unique name is chosen
(``base``, ``base_1``, ...). If ``network`` is given,
the session is pointed at it first. Returns the name actually used.

Input parameters:

- `name` (string, required)
- `network`
- `overwrite` (boolean)
- `zip_base64` (string, required)

### `batfish_run_question` (~660 tokens)

Batfish Run Question

Run a Batfish question and return its JSON-safe rows.

\- ``fun`` is the pybatfish question function name (see
  \``batfish_list_questions``); ``options`` is its keyword-argument dict.
\- ``snapshot`` runs the question on that snapshot (the session's
  current snapshot otherwise).
\- ``reference_snapshot`` + ``snapshot`` runs a differential question
  comparing the two; both are required for differential questions. In the
  answer, ``Snapshot_*`` columns come from ``snapshot`` (the snapshot
  under test) and ``Reference_*`` columns come from ``reference_snapshot``
  (the baseline).
\- ``network`` points the session at a network first, if given.
\- ``debug=True`` includes the raw Batfish exception log in the response.
\- ``trace_detail`` controls trace columns (``Traces``, ``Snapshot_Traces``,
  \``Reference_Traces``): ``"summary"`` (default) keeps disposition, node
  path, and hop count; ``"none"`` drops the trace columns but keeps the
  trace counts; ``"full"`` returns the original hop-by-hop traces.
\- ``max_rows`` caps the number of returned rows (default 50). Use ``0``
  for no limit; ``total_rows``, ``returned_rows``, and ``truncated`` report
  whether the cap was applied.
\- A named ``snapshot``/``reference_snapshot`` must exist in the network;
  otherwise a ``ValueError`` lists the available snapshots.

Returns ``{fun, snapshot, reference_snapshot, status, rows,
removed_columns, total_rows, returned_rows, truncated}`` where ``rows`` is
a list of row dicts. A ``differentialReachability`` answer also includes
\``trace_columns``, which maps ``Snapshot_Traces`` to the ``snapshot``
argument and ``Reference_Traces`` to ``reference_snapshot``. A Batfish
failure returns ``{status: "error", code, message, rows: []}`` instead of
raising; known codes include ``SNAPSHOT_INCOMPATIBLE``,
\``INVALID_ARGUMENT``, ``INVALID_PORT_SPEC``, and
\``BIDIRECTIONAL_REQUIRES_DST``.

Header values are Batfish specifiers: ``srcIps``/``dstIps`` accept IPs,
prefixes, node names, or named IP spaces; ``…

Input parameters:

- `debug` (boolean)
- `fun` (string, required)
- `max_rows` (integer)
- `network`
- `options`
- `reference_snapshot`
- `snapshot`
- `trace_detail` (string)

### `batfish_list_assertions` (~145 tokens)

Batfish List Assertions

List the assertions available (registry + live pybatfish names).

Returns ``{snapshot, answer, specs}``:

\- ``snapshot`` / ``answer``: assertion names available in the installed
  pybatfish, grouped by how they are called (session-bound vs
  answer-based).
\- ``specs``: the curated registry ``{type: {label, description, group,
  phase, call, needs_question, params}}`` — each param is
  \``{name, type, optional, hint}``, where ``hint`` describes complex
  types (e.g. ``HeaderConstraints``) so you can build ``params``.

### `batfish_run_assertion` (~430 tokens)

Batfish Run Assertion

Validate and run one assertion on a snapshot.

\- ``name``: assertion type (see ``batfish_list_assertions``).
\- ``params``: its parameters, e.g. ``{"headers": {"dstIps":
  "8.8.8.8", "ipProtocols": ["TCP"], "dstPorts": "443"}}`` for
  \``assert_flows_succeed``.
\- ``question``: ``{"fun": ..., "options": {...}}`` — required for
  answer-based assertions (``assert_zero_results``, ``assert_num_results``,
  \``assert_min_results``); the question is run first and its answer checked.
\- ``snapshot`` / ``network``: run on that snapshot (and network first),
  otherwise the session's current ones.
\- ``debug=True`` includes the raw Batfish error text on failures.

Returns ``{type, status (pass/fail/error), message, snapshot, ran_at,
runtime, fun?, answer_rows?, details?, code?}``. Failure messages are
short: ``message`` is the one-line summary, and failing rows are returned
as ``answer_rows`` when they can be parsed; otherwise ``details`` holds a
capped records-style payload. Validation problems are returned as
\``status: "error"`` with an ``errors`` list (nothing is run).

Header fields follow Batfish rules: ``srcIps``/``dstIps`` accept IPs,
prefixes, and node names; ``srcPorts``/``dstPorts`` are string specs such
as ``"443"``. When ``ipProtocols`` is omitted, Batfish tests ICMP, so set
\``ipProtocols`` and ``dstPorts`` for service-level assertions. Prefer node
names, interface locations, or explicit host IPs: broad prefixes may make
Batfish choose representative flows with network-address sources.

Input parameters:

- `debug` (boolean)
- `name` (string, required)
- `network`
- `params`
- `question`
- `snapshot`

### `batfish_run_assertion_suite` (~329 tokens)

Batfish Run Assertion Suite

Validate and run an assertion suite (YAML text) on a snapshot.

\``suite_yaml`` uses the suite schema (see ``examples/assertions.yaml``)::

    version: 1
    assertions:
      - type: assert_flows_succeed
        params:
          startLocation: as1border1
          headers:
            dstIps: 2.128.0.101
            ipProtocols: [TCP]
            dstPorts: "443"

Header fields follow Batfish rules: ``srcIps``/``dstIps`` accept IPs,
prefixes, and node names; ``srcPorts``/``dstPorts`` are string specs such
as ``"443"``. Without ``ipProtocols``, Batfish tests ICMP. Prefer node
names, interface locations, or explicit host IPs over broad prefixes,
which may make Batfish choose representative flows with network-address
sources.

All-or-nothing: if the suite is invalid, nothing runs and the result is
\``{results: [], errors: [...], summary: {...}}``. Otherwise results are
\``{type, status, message, snapshot, ran_at, runtime, fun?, answer_rows?,
details?, code?}`` per assertion, plus a ``summary`` of pass/fail/error
counts. Failure messages use a one-line summary; rows are returned as
\``answer_rows`` when parseable, otherwise as capped ``details``.

Input parameters:

- `debug` (boolean)
- `network`
- `snapshot`
- `suite_yaml` (string, required)

### `batfish_fork_snapshot` (~284 tokens)

Batfish Fork Snapshot

Fork a snapshot, optionally failing (deactivating) nodes/interfaces.

\- ``base_name``: the snapshot to fork.
\- ``name``: the fork's name (sanitized with ``safe_snapshot_name``);
  defaults to ``<base>_Fail``. Unless ``overwrite`` is true, an
  existing name is kept and a unique one is chosen
  (``name``, ``name_1``, ...).
\- ``failed_nodes``: node names to deactivate in the fork.
\- ``failed_interfaces``: interfaces to deactivate, each as a
  \``node[interface]`` string (for example ``"r1[Gi0/0]"``) or as a
  \``{"hostname": "r1", "interface": "Gi0/0"}`` mapping. Bare node names
  are rejected; use ``failed_nodes`` for those.
\- The failure-testing flow is: fork, then diff the fork against the base
  with a differential question.
\- ``network``: the network both snapshots live in, if given.

Returns ``{name, base_name}`` — the name actually used.

Input parameters:

- `base_name` (string, required)
- `failed_interfaces`
- `failed_nodes`
- `name`
- `network`
- `overwrite` (boolean)

### `batfish_get_topology` (~140 tokens)

Batfish Get Topology

Return the topology graph of a snapshot as nodes/edges.

\- ``kind="layer3"`` (default): L3 links from ``layer3Edges``
  (node — interface <-> interface — node, so edges carry a ``title``
  like ``"r1 (Gi0/0) <---> r2 (Gi0/0)"``).
\- ``kind="routing"``: routing adjacencies from ``bgpEdges``.

Returns ``{kind, snapshot, node_count, edge_count, nodes, edges}``.

Input parameters:

- `kind` (string)
- `network`
- `snapshot`

## Diagnostics

Captured diagnostic sections: Provenance, Install scripts, Dependencies. The full working is on the page: https://verifymcp.io/servers/martimy-batfish-q-mcp/batfish-q-mcp#diagnostics

## Score history

- 2026-11-21: 69
- 2026-11-20: 53
- 2026-11-19: 68
- 2026-11-18: 67
- 2026-11-17: 52
- 2026-11-16: 66
- 2026-11-15: 66
- 2026-11-14: 65
- 2026-11-13: 65
- 2026-11-12: 49
- 2026-11-11: 66
- 2026-11-10: 51
- 2026-11-09: 51

## Common questions

### What is the io.github.martimy/batfish-q-mcp server?

io.github.martimy/batfish-q-mcp is listed in the public MCP registry as io.github.martimy/batfish-q-mcp. An MCP server exposing Batfish tools so AI assistants can query network configs in plain language. This page covers its PyPI package (batfish-q-mcp).

### Is the io.github.martimy/batfish-q-mcp server safe to use?

io.github.martimy/batfish-q-mcp scores 69 out of 100 on VerifyMCP. We found no known CVEs affecting it as of 21 November 2026. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.

### What tools does the io.github.martimy/batfish-q-mcp server expose?

io.github.martimy/batfish-q-mcp exposes 12 tools: batfish_find_questions, batfish_list_questions, batfish_get_question, batfish_list_snapshots, batfish_delete_snapshot, and 7 more. Their descriptions and schemas cost roughly 2,940 tokens of context every time the server is loaded.

### Is the io.github.martimy/batfish-q-mcp server still maintained?

io.github.martimy/batfish-q-mcp is still listed as active in the MCP registry. We last reached this channel on 21 November 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.

### What licence is the io.github.martimy/batfish-q-mcp server under?

io.github.martimy/batfish-q-mcp declares the Apache-2.0 licence, which is OSI-approved. That covers the source only, and says nothing about the cost of any service it calls.

### What did VerifyMCP test on the io.github.martimy/batfish-q-mcp server?

VerifyMCP ran 16 checks on io.github.martimy/batfish-q-mcp, covering Malware scan, Known CVEs, Install scripts, Dependency health and 12 more. Endpoint Security and Transport & Reachability do not apply to a PyPI package, so they were not tested. The score does not measure everything, and the scoring documentation lists what it leaves out.

## Links

- PyPI project: https://pypi.org/project/batfish-q-mcp/
- Socket report: https://socket.dev/pypi/package/batfish-q-mcp
- Repository: https://github.com/martimy/batfish-q-mcp
- Changelog RSS feed: https://verifymcp.io/servers/martimy-batfish-q-mcp/batfish-q-mcp.xml
- Changelog JSON feed: https://verifymcp.io/servers/martimy-batfish-q-mcp/batfish-q-mcp/changelog.json
- Trust report (JSON): https://verifymcp.io/servers/martimy-batfish-q-mcp/batfish-q-mcp.json
- HTML version of this page: https://verifymcp.io/servers/martimy-batfish-q-mcp/batfish-q-mcp
