bigfix-root-mcp
This is a read-only BigFix root-server MCP server for relevance queries, client fast queries, and scoped REST lookups.
Evaluate session relevance against the root server with bounded paging.
Statically analyze relevance offline and search the offline inspector reference.
Submit, poll, and page client fast-query results across scoped computers.
Evaluate client relevance locally with qna targets, and discover/list qna targets.
Read server info, sites, computer records, computer groups, applicable fixlets, actions/status, content, operators, roles, dashboard variables, and whoami.
Use a read-only GET escape hatch for any
/api/path.Validate BES XML offline.
Respect configured operator scope; results may be a lower bound unless
whoamireports main-operator status.Write tools are not present in this schema; capabilities are read-only by default.
Provides read-only tools for interacting with the HCL BigFix root server REST API, including session relevance queries, client fast queries, server info retrieval, site listing, computer group and operator lookups, dashboard variable reads, and a generic read-only API escape hatch.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@bigfix-root-mcp how many computers are reporting in my enterprise"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
bigfix-root-mcp
A minimal, read-only MCP server around the besapi library, exposing the HCL BigFix root server REST API to MCP clients. Built on FastMCP 4 (stateless). Session relevance is evaluated with bigfix-remote-session-relevance (see Session relevance); every other REST call goes through besapi.
Focus: session relevance queries (data the server already has) and client fast query (live questions answered by BigFix agents), plus a few read-only helpers.
Strongly recommend using the official BigFix Platform MCP server instead: https://help.hcl-software.com/bigfix/11.0/platform/Platform/MCP/c_introduction.html
The capabilities of this MCP server are intentionally limited, where as the official one is not.
Tools
Tool | Purpose |
| Evaluate session relevance on the root server; returns the JSON envelope ( |
| Statically analyze a relevance expression offline - parse, types, dialect, unknown inspectors with suggestions, complexity. Never evaluates it. |
| Fuzzy-search the offline inspector reference by name or phrase. |
| Search a local, offline index of relevance documentation and worked examples (needs |
| Search a local index of your own existing fixlets and analyses (built from a directory or a git repository: relevance, analysis properties and action script templates), with the habits counted across them (needs |
| Submit a client fast query, return its |
| Fetch current (cumulative) results for a query ID; safe to call repeatedly. |
| Submit + poll in one call with progress notifications; stops on expected count reached, results stable, or timeout. |
| Root server version info ( |
| Sites visible to the configured operator. |
| Look up a group by name - requires an explicit |
| Look up a console operator by name. |
| Read a dashboard datastore variable. |
| Configured user/root server, main-operator status, write-gate state; connectivity smoke test. |
| Read-only escape hatch: GET any |
| One computer's full record ( |
| Find computers by case-insensitive name substring. |
| Content currently relevant to one computer. |
| An action's definition, and its per-computer execution state. |
| Actions visible to the configured operator. |
| Search fixlets/tasks/analyses/baselines by name across sites; resolves the |
| One fixlet, task, analysis or baseline by site path and ID. |
| Console operators and roles (master operator only). |
| Validate BES XML against the BigFix schemas. No server call. |
Relevance analysis (advisory)
The relevance-taking tools statically analyze their relevance with
bigfix-relevance-analyzer
before sending it (dialect pinned per tool). The analysis is advisory
only: even a query the analyzer rejects still goes to the server, because
the analyzer's inspector table is a snapshot - an unknown inspector there may
still exist on the live server. When there are findings, the response carries
an analysis key (findings, suggestions, dialect mismatch); a clean query
adds nothing. Server-side relevance errors gain a Static analysis: appendix
with the findings and did-you-mean suggestions, so a typo'd inspector is a
one-round-trip fix.
qna fast evaluation
Registered by default; absent when every target source is disabled - see qna evaluation.
Tool | Purpose |
| Evaluate client relevance with the |
| List the inventory targets, which inventory file is in use, whether auto-discovery may run, and whether container images are allowed. |
| Find qna targets that work on the server's host and add them to |
Write tools (opt-in)
Absent unless BIGFIX_ALLOW_WRITES is set - see Writes.
Tool | Purpose |
| Stop an in-flight action ( |
| Set a dashboard datastore variable. |
| Create/update custom content in a site. Does not deploy it. |
Result bounding
Every tool that can return an unbounded payload is windowed and says so.
List-shaped tools take limit/offset and report returned,
total_available and truncated; blob-shaped tools report truncated and
total_chars, and drop an oversized payload rather than cut it into something
that looks complete.
This is not optional politeness: BigFix relevance has no row-limiting
operator (first, firsts, items, elements are all undefined), so
bounding the response is the only way to bound a result. find_content on the
reference deployment matches 12,395 fixlets.
Related MCP server: MSSQL-MCP
Resources and prompts
Relevance is the hard part, so the server ships reference material clients can pull on demand rather than repeating it in every tool description:
Resource | Contents |
| Session relevance that works - every expression verified against a live root server - plus the operators that don't exist. |
| Client (fast query) relevance, targeting forms, reading cumulative results. |
| Rules that prevent most relevance errors, the common error messages with their usual causes, and how applicability clauses combine. Every example is checked with the analyzer. |
| Documented client-relevance patterns for files, registry, applications, services, OS, versions, text and WMI. Every example is checked with the analyzer. |
| Which tool answers which question, how to read bounded responses, what operator scope means. |
| Client versus session relevance: where each is evaluated, which one a tool expects. |
| Client relevance language reference (from bigfix-relevance-analyzer). |
| Session relevance language reference (from bigfix-relevance-analyzer). |
Prompts: diagnose_computer, patch_status, find_stale_agents,
troubleshoot_relevance, write_relevance, write_actionscript, write_fixlet.
write_relevance(goal, dialect) walks a model through writing relevance: look it
up with search_relevance_docs (and search_reference_fixlets, for similar existing
content), check names with search_inspectors, draft,
analyze_relevance, evaluate with a bounded query, and report only what was
verified. If BIGFIX_RELEVANCE_CONVENTIONS names a markdown file, its text is
added as house conventions (how your team treats proxy agents, guard idioms, and
so on; HTML comments in the file are for people and are not sent). Two starting points are
tracked: corpus/conventions.md, an editable default (it excludes proxy
agent contexts) that you can point the variable at as it is or copy and edit, and the
commented template
docs/relevance-conventions.example.md.
write_actionscript(goal, platform) does the same for an action script: look up the
commands in the indexed action script documentation, find a similar script as a template
with search_reference_fixlets (role='actionscript'), draft, check every {...}
relevance substitution with analyze_relevance, and report what was checked. A script
can be checked but not run, so it never says one works, never invents a download URL or
checksum, and never puts a credential in a script. write_fixlet(goal, platform) joins
the two: applicability relevance and an action script that agree with each other,
assembled as BES XML and checked offline with validate_bes_xml. It does not import or
deploy anything.
Relevance errors also carry a cause hint: the server recognizes the common failure shapes (a non-existent limiting operator, client relevance in a session query, singular-vs-plural) and appends what to do instead, so a bad expression is a retry rather than a dead end.
Client fast query semantics
Client queries are answered by live agents: results accumulate at
/api/clientqueryresults/{id} over seconds to minutes as clients report in,
and there is no completion flag. The client_query tool polls with three
termination heuristics (reported in stop_reason):
expected_count_reached- as many distinct computers reported as targeted;results_stable- no new computers forstable_pollsconsecutive polls;timeout- partial results at timeout are a normal outcome (offline agents never report), not an error.
For long waits, use client_query_submit then client_query_results
repeatedly instead of a single blocking call.
The knowledge base: adding sources and regenerating the indexes
The server can search two local indexes. Both are optional, offline and read-only, and both are built by tools in this repository, not downloaded.
Index | Built from | Tool that reads it | Variable | File |
Documentation | Web pages, PDFs and git repositories of public documentation, plus any private documents you list |
|
|
|
Reference fixlets |
|
|
|
|
Everything the tools download, convert or build lives under corpus/ and is ignored by git
(see corpus/README.md). Public availability is not permission to
redistribute: only add sources you are cleared to use, and note that the reference
fixlet index holds your own company content, so never commit, package or share it.
Neither index is shipped: each user builds both on their own machine from the source
lists. The documentation index can hold private documents too, so the same applies to it.
Run every command from the repository root. uv sync installs the development group,
which includes pypdf, needed only to read PDFs. Use uv run python -m ..., or plain
python -m ... with the project environment active. Every step has a --dry-run that
changes nothing: use it first.
Quick start: build both indexes from a fresh clone
These commands build both indexes from the committed source lists (corpus/GIT_SOURCES.csv
and corpus/MANIFEST.csv), then register the server with Claude Code. Run them from the
root of the clone:
uv sync # the dev group, including pypdf
uv run python -m tools.ingest.gitsource # the pinned documentation repositories
uv run python -m tools.ingest.fetch # the URL sources, each checked by SHA-256
uv run python -m tools.ingest.build # writes corpus/index/relevance.sqlite
uv run python -m tools.ingest.fixletbuild --all # writes corpus/index/fixlets.sqlite
claude mcp add bigfix-root --scope user \
-e BIGFIX_KNOWLEDGE_INDEX="$PWD/corpus/index/relevance.sqlite" \
-e BIGFIX_FIXLET_INDEX="$PWD/corpus/index/fixlets.sqlite" \
-e BIGFIX_RELEVANCE_CONVENTIONS="$PWD/corpus/conventions.md" \
-- uv run --project "$PWD" bigfix-root-mcpRun the server from the checkout (
uv run --project), not withuvx bigfix-root-mcp: the published package does not have the index tools and prompts in this branch. Use absolute paths; on Windows write them out in full.BIGFIX_RELEVANCE_CONVENTIONSis optional. It loads the committed default conventions, which you can edit.The search tools and prompts work without a BigFix connection. The other tools also need
BES_ROOT_SERVER,BES_USER_NAMEandBES_PASSWORD, or a~/besapi.conf(see Configuration).fixletbuilddoes not need the downloads, so it can run whilefetchis running.fetchwaits between requests to one host, so it is the slow step. If an upstream page has changed since its hash was committed,fetchdownloads it and records the new hash incorpus/MANIFEST.csv, which then shows as modified in git. That is expected: keep the change, or commit it to move the pin.
A run on 2026-10-26 (Windows, one machine) took about 14 minutes for fetch, about a
minute each for build and fixletbuild, and seconds for the rest. It gave a documentation
index of 10,341 chunks and 1,206 examples from 422 sources (2 of the 420 URL sources had
changed upstream), and a reference index of 22,324 rows from bigfix/CommunityContent and
bigfix/content. Your own sources, and any other repositories, come from
corpus/local-sources.csv, which is not in the clone; add them as described below and
build again.
Add to the documentation index
To add | Edit | Then run |
A web page (a URL) | a row in |
|
A PDF (a URL) | a row in |
|
A git repository of documentation | a row in |
|
A URL (web page or PDF). Add one row to corpus/MANIFEST.csv. The columns are
id, path, source_url, title, retrieved_on, license, bigfix_version, dialect, sha256, notes:
my-guide,,https://example.com/docs/my-guide.pdf,My Guide,,Public; use covered by sign-off,11.0,client,,added 2026-10-24idis a short name (letters, digits,.,_,-).dialectissession,clientorboth; blank means unknown. Leavepath,retrieved_onandsha256blank: the fetch step fills them in and records the file's SHA-256, so a later change upstream shows as a manifest diff.Supported types are
.pdf,.html/.htmand.md/.markdown/.txt. The stored file name takes its extension from the URL. A page whose URL has no.htmlextension would be stored as.binand skipped, so putmy-page.htmlin thepathcolumn yourself.Fetching honours
robots.txt, waits between requests to one host and caps response size. It only fetcheshttpandhttps.
python -m tools.ingest.fetch --dry-run # download and report, write nothing
python -m tools.ingest.fetch # fetch, record hashes in MANIFEST.csv
python -m tools.ingest.fetch --only my-guideA git repository. Add one row to corpus/GIT_SOURCES.csv. The columns are
id, repo_url, branch, commit, subpath, license, pinned_on, notes. The commit must be a
full 40-character SHA and subpath must name the folder to read, so every build uses the
same bytes. Find the commit with git ls-remote <repo_url> <branch>:
my-docs,https://github.com/example/docs.git,main,0123456789abcdef0123456789abcdef01234567,site/pages,Apache-2.0,2026-10-24,pinned todayTo read two folders of one repository, add two rows with different ids and the same commit.
To update a source, change its commit and run the steps again.
python -m tools.ingest.gitsource --dry-run
python -m tools.ingest.gitsourceA private document (a PDF, HTML, markdown or text file that must stay local). Add a
file row to the untracked corpus/local-sources.csv, the same private list the fixlet
index reads; only the documentation index uses file rows. The file is read in place on
every build and its SHA-256 is recorded; only its file name is stored as its origin:
team-doc,file,C:/path/to/guide.pdf,,,,team,private; read in placeRegenerate the documentation index. The index is rebuilt from scratch from every row, so this is also how you pick up a change or remove a source (delete its row first):
python -m tools.ingest.build --dry-run # converts and scans, writes nothing
python -m tools.ingest.build # writes corpus/index/relevance.sqliteThe report lists each source's files, chunks and examples. It also scans for credentials and
refuses to write the index if it finds a high-confidence one (exit code 3); a known false
positive can be allowed in corpus/SCAN_ALLOW.csv with a reason. Point
BIGFIX_KNOWLEDGE_INDEX at the file. It is read on every call, so a rebuilt index is used
without restarting the server.
Add to the reference fixlet index
To add | Edit | Then run |
A directory of | a row in |
|
A private git repository of | a row in |
|
A public git repository of | a row in |
|
There are two source lists. Private sources go in corpus/local-sources.csv, which is
ignored by git because a company path or an internal repository URL is itself internal.
Public sources go in the tracked corpus/GIT_SOURCES.csv, the same list the
documentation index uses, pinned to a commit. Its optional content column says which index
a row feeds (docs, the default, fixlets, or docs+fixlets) and its optional group
column names the group. fixletbuild --all reads both lists. Copy the template for the
private list and edit it:
cp docs/local-sources.example.csv corpus/local-sources.csvThe columns of local-sources.csv are id, kind, location, branch, commit, subpath, group, notes:
team-fixlets,dir,C:/path/to/bes-files,,,,team,a working tree
team-repo,git,https://git.example.com/org/repo.git,main,,content/fixlets,team,internal repositoryA public repository goes in corpus/GIT_SOURCES.csv with a full 40-character commit, a
subpath (. for the whole repository), and the two optional columns:
public-repo,https://github.com/example/public-content,,0123456789abcdef0123456789abcdef01234567,.,MIT,2026-10-26,example content,fixlets,referenceA directory is read in place and never modified. Every
.besfile under it is found, in any letter case. Links and junctions are not followed. Adirrow may also name one.besfile (with nosubpath), to add a single item without the rest of its folder.A git repository is checked out under
corpus/raw/fixlets/<id>/. A blankcommitmeans the branch tip at the moment it is read; the commit is recorded. Put a full SHA there to read exactly the same content again. Usehttps(git must be able to sign in without a prompt; a password in a URL is refused) or, with--allow-scheme ssh, ansshURL.groupdecides what is counted together. The habits the index reports are counted per group and never pooled, so give your own sources one group and other people's content another. A source with no group counts alone.
python -m tools.ingest.fixlets --source team-fixlets --dry-run # check one source
python -m tools.ingest.fixlets --source team-fixlets # read it, record when
python -m tools.ingest.fixletbuild --all --dry-run # analyse every listed source
python -m tools.ingest.fixletbuild --all # write corpus/index/fixlets.sqliteFor a one-off, skip the list: python -m tools.ingest.fixlets --dir PATH or
--git URL [--branch B] [--commit SHA] [--subpath P].
The index is built from all the sources you name at once and rebuilt from scratch, so
always build with --all (or repeat --source). It holds three kinds of row: applicability
relevance of fixlets and tasks, analysis properties, and action scripts, each stored as a
template with its relevance substitutions listed separately. It also counts the habits that
recur, per group and platform. A credential found in relevance, a description or a script is
left out and reported by file and rule, never by value. Point BIGFIX_FIXLET_INDEX at the
file. The step-by-step guide, with a worked example for each kind of source, is
docs/reference-fixlets.md.
Check and keep it current
Ask for something the sources cover.
search_relevance_docsanswers withchunksandexamples;search_reference_fixletsanswers withresultsandconventions. Either answersavailable: falsewith the reason and how to enable it when its variable is unset, its file is missing, or the index was built by a different version. A version mismatch means rebuild.Rebuild whenever a source changes. Every real read of a reference source appends to
corpus/index/fixlet-reads.jsonl: when it was read (UTC), the commit (git), a fingerprint of the files and counts.To judge answers fairly, set
BIGFIX_FIXLET_HOLDOUTto the item ids a question came from; they are removed, with their action scripts, from every search.The write prompts that use these indexes are
write_relevance,write_actionscriptandwrite_fixlet(above). Team rules belong inBIGFIX_RELEVANCE_CONVENTIONS, not in the indexes.
Configuration
Environment variables win over config files:
Setting | Env var / | Default |
Root server URL |
| - |
REST operator |
| - |
Password |
| - |
Write tools |
| off |
TLS verification |
| unset ( |
qna inventory |
|
|
qna auto-discovery |
| on |
qna containers |
| on |
Knowledge index |
| unset ( |
Reference fixlet index |
| |
Relevance conventions |
| unset (no conventions) |
Transport |
|
|
Config files are searched in besapi's order: /etc/besapi.conf,
~/besapi.conf, ~/.besapi.conf, ./besapi.conf - same
[besapi] section format as besapi/bescli, so an existing config just works.
Prefer keeping credentials in ~/besapi.conf over MCP client config files.
Example MCP client config (see .mcp.json):
{
"mcpServers": {
"bigfix-root": {
"command": "uvx",
"args": ["bigfix-root-mcp"]
}
}
}Install / run
Published on PyPI. Requires Python 3.11+.
With uv (preferred)
No install step - uvx fetches and runs it in a throwaway environment, which is
also what the MCP client configuration above uses:
uvx bigfix-root-mcpTo keep it on PATH instead, as a managed tool:
uv tool install bigfix-root-mcp
bigfix-root-mcpWith pip
pip install bigfix-root-mcp
bigfix-root-mcp # or: python -m bigfix_root_mcpFrom a checkout
uv 0.12+ required:
uv sync
uv run bigfix-root-mcp # or: uv run python -m bigfix_root_mcpVerifying a download
Every release since v0.1.3
also attaches the wheel and sdist with a SHA256SUMS.txt, checkable with
sha256sum -c SHA256SUMS.txt.
Smoke test against a live root server with MCP Inspector:
npx @modelcontextprotocol/inspector bigfix-root-mcpthen call whoami, session_relevance_query with number of bes computers,
and client_query targeting a known computer ID.
Operator scope
Every result is limited to what the configured REST operator can see. Only a
master operator has full visibility; a regular operator can never be
certain its view is complete, and cannot distinguish "does not exist" from
"outside my scope". So number of bes computers returning 35 means 35
computers visible to this operator - a lower bound, not the BigFix total.
whoami reports is_main_operator for exactly this reason: check it before
treating any result as the full state of BigFix. The tool descriptions carry
this caveat so LLM clients don't overstate scoped results.
Safety and design notes
Read-only by default: with
BIGFIX_ALLOW_WRITESunset, only read tools are registered - the write tools do not exist as far as any client can tell. One nuance: submitting a client query does create a query object server-side, but agents only evaluate relevance against it - no managed-endpoint state changes.Client fast query is a powerful read.
client_querywithtarget_allevaluates arbitrary client relevance on every agent the operator can see, and the BigFix agent runs as SYSTEM/root. That can read file contents, registry values and process lists fleet-wide, and the results come back in the tool response. Scope the configured operator to the smallest useful set of computers;whoami.is_main_operatortells you which you have.Explicit site paths: this server never uses besapi's mutable "current site path" connection state (
set_current_site_path/get_current_site_path- a bescli convenience); tools that need a site take a requiredsite_pathparameter.Stdout hygiene: stdout belongs to the MCP stdio transport; all logging goes to stderr, and config loading avoids besapi helpers that print.
TLS: with
BES_SSL_VERIFYunset (ortofu), session relevance trusts on first use: a CA-valid certificate is used as is, a self-signed one (the BigFix default) is pinned on first contact in~/.bigfix/.remote_session_known_certs.toml- shared with the bigfix-remote-session-relevance CLI - and a different certificate later is refused before any credentials are sent. Remove the entry (or runbigfix-remote-session-relevance --forget-cert HOST:PORT) once a legitimately changed certificate is verified out of band. The besapi tools have no pinning and stay unverified in that mode, matching besapi. An explicitfalseturns verification off for both;true(honouringREQUESTS_CA_BUNDLE/CURL_CA_BUNDLE) or a CA bundle path verifies both and pins nothing - use one of those for anything beyond a lab.HTTPS_PROXY/NO_PROXYare honoured by the besapi tools only; session relevance connects directly.Generic BigFix logic here is written to be upstreamed into besapi - see docs/besapi-proposals.md.
Session relevance
session_relevance_query, find_computers and find_content evaluate
through the REST backend of
bigfix-remote-session-relevance,
using the same connection settings as everything else (env vars or
besapi.conf); its own ~/.bigfix config, certificate pinning and
deployment discovery are not used. The reason is the root server's
behaviour when it can reach a BigFix Explorer: it forwards /api/query to
Explorer, which rejects besapi's double-encoded form post with "This
expression contained a character which is not allowed" - in practice any
query containing a space. The library sends a JSON body first and falls back
to besapi's form encoding only when the server answers "no reachable BigFix
Explorer", so both setups evaluate the query exactly as written.
qna evaluation
bigfix-remote-client-relevance
is a base dependency, so qna_eval_client_relevance / qna_list_targets
are registered by default; they are absent only when both target sources are
off (BIGFIX_QNA_INVENTORY=0 and BIGFIX_QNA_CONTAINERS=0). The [qna]
extra still exists so older install commands keep working, but adds nothing.
It evaluates client relevance with
the BigFix qna binary on lab targets in about a second per warm run - the
fast half of the feedback loop next to the advisory analysis.
What it is not: qna runs on the target machine, not through the BigFix
deployment. No operator scope, no site subscriptions, no client settings -
inspectors that depend on deployment state will differ from client_query.
Iterate here, confirm on real agents with client_query. (The package's
Fast Query transport is an upstream stub; this server does not expose it.)
Targets are deliberately constrained:
Container images (
ubuntu:22.04, ...) may be passed by the caller; needs docker or podman on the server host. First use of an image is slow (agent artifact download + derived image build); later runs are ~1s. SetBIGFIX_QNA_CONTAINERS=0to forbid these.Inventory hosts come only from a remote_clients.toml on the server (the package's inventory format: ssh/local/container/online_evaluator entries).
BIGFIX_QNA_INVENTORYnames one; unset, the server uses the same default as the package's CLI:~/.bigfix/remote_clients.toml, then the all-users config directory (/Library/Application Support/bigfix,/etc/xdg/bigfix,C:\ProgramData\bigfix). Unlike the CLI it never reads./remote_clients.toml, since an MCP server's working directory is wherever its client launched it.BIGFIX_QNA_INVENTORY=0turns the inventory off. The MCP client can pick entries by name but can never supply ssh hosts, users, orbecomeflags of its own.qna_list_targetsshows the file in use.No targets named means every inventory host, as with the CLI (qna only reads), up to 20 per run. An
online_evaluatorentry sends the client relevance to developer.bigfix.com, so name targets explicitly to keep a query off it.Auto-discovery: the package's non-interactive discovery probes local qna, a downloaded qna (cached by the package), the container engine's images and developer.bigfix.com, then adds what works to
~/.bigfix/remote_clients.toml; it can take minutes. Runs are one at a time. It is refused while the inventory in use is another file (the all-users one, say), because the new~/.bigfixfile would hide it. As with the CLI, it runs by itself only on a first run: one that names no targets when no inventory file exists. Once the file exists, even with no hosts, it runs only when theqna_discover_targetstool is called (the CLI's--auto-discovery). With aBIGFIX_QNA_INVENTORYpath (that file is the admin's) orBIGFIX_QNA_AUTO_DISCOVERY=0it never runs and that tool is not registered. It never uses the interactive SSH discovery and never prompts. When aqna_eval_client_relevancerun finds no targets (an empty inventory, a name missing from an empty one) or returns no result rows at all, the error or the payload'shintsuggestsqna_discover_targets. Error rows count as results. If discovery ran in the last 15 minutes, it says what that run added and where to add hosts by hand instead.
Security notes: qna executes on the targets; the controller downloads BigFix
agent artifacts from support.bigfix.com (SHA256-verified against the release
site's sums) on first use of a version, so the server host makes outbound
requests; every run, and every auto-discovery, leaves a BIGFIX QNA audit
line on stderr.
Writes
Set BIGFIX_ALLOW_WRITES=true to register the three write tools. The flag
controls registration, so with it off there is nothing to call.
Two guardrails apply to all of them:
dry_rundefaults to true. The response describes the call that would be made and nothing is sent. A write only happens on an explicitdry_run=false.Every attempt is audit-logged to stderr as one
BIGFIX WRITEline with the operator, target, dry-run flag and outcome.
The set is limited on purpose to operations whose blast radius is reversible
or nil. import_bes_content creates content; it does not run it - a fixlet
imported this way does nothing until somebody deploys an action against it in
the console.
Not implemented, and not to be added without their own design round:
deploying actions (POST /api/actions), any DELETE, creating sites or
operators, and file upload. Deploying an action is arbitrary code execution as
root across the fleet, which is a different category of risk from anything
here.
Documentation
Doc | Contents |
Client fast query protocol reference: endpoints, payloads, live-captured result schema, termination heuristics and their tradeoffs. | |
besapi behaviors this wrapper depends on or works around (error surfacing, connection lifecycle, return shapes, site-path state). | |
Why the server is shaped this way, plus FastMCP 4 beta specifics. | |
Proposed upstream besapi changes that would let this project shrink. | |
Live-verified REST paths, site-path rules, and relevance findings (including the operators that don't exist). | |
Threat model and findings for the tool surface. |
Development
Requires Python 3.11+ and uv 0.12+. uv sync
creates .venv from the committed uv.lock and installs the dev dependency
group; no manual venv or pip install -e step.
uv sync
uv run pytestLinting, formatting, type checking and the packaging checks all run through
pre-commit (ruff, mypy, bandit, slyp, zizmor, and the uv lock/build checks).
Install both hook types - some checks are deliberately deferred to pre-push
because they are too slow to want on every commit:
uv run pre-commit install --hook-type pre-commit --hook-type pre-pushUseful invocations:
uv run pre-commit run --all-files # the commit-stage hooks
uv run pre-commit run --all-files --hook-stage manual # everything, as CI runs itTests run entirely offline against a scripted fake BESConnection, including
in-memory end-to-end MCP calls via fastmcp.Client.
Available Tools
27 toolsanalyze_relevanceAnalyze RelevanceA
Statically analyze a relevance expression WITHOUT evaluating it anywhere.
Offline and instant: checks that the expression parses (with a positioned error when it does not), infers types, classifies the dialect (session vs client), flags inspectors no reference dump defines, finds unbound 'it', and scores complexity/evaluation cost. Use it to validate a query before session_relevance_query or client_query, or to understand a relevance error after one.
Advisory: the inspector table is a snapshot, so an unknown inspector is a warning (the live server may still know it), and a clean report does not guarantee the server will accept the query.
Inputs: relevance (required), dialect, platform, include_sexpr. Returns: object
api_getApi GetA
Read-only escape hatch: GET any BigFix REST API path under /api/.
GET is non-mutating across the BigFix REST API. Use path 'help' to discover available endpoints. Response text is capped at max_chars; total_chars reports the full length.
Inputs: path (required), max_chars. Returns: object
applicable_fixletsApplicable FixletsA
Content currently relevant to one computer (/api/computer/{id}/fixlets).
This is the patch/compliance question: what BigFix currently considers applicable to that machine.
Inputs: computer_id (required). Returns: object
client_queryClient QueryA
Submit a BigFix client (fast) query and wait for results, polling until done or timeout. Targeting: set exactly one of target_all, target_computer_ids, target_computer_names, or target_relevance (client relevance evaluated on each agent to decide applicability). Targeting is limited to the configured operator's scope, so target_all means all computers this operator can see, not necessarily all computers in BigFix.
Inputs: query_text (required), limit, offset, target_all, +7 more. Returns: object
client_query_resultsClient Query ResultsA
Fetch current results for a previously submitted client fast query.
Results are cumulative and there is no completion flag: safe and cheap to call repeatedly until reported_count stops growing or the expected number of computers have reported.
reported_count and result_row_count always describe the full result set; the returned rows are windowed by limit/offset.
Inputs: query_id (required), limit, offset. Returns: object
client_query_submitClient Query SubmitA
Submit a BigFix client (fast) query. Targeting: set exactly one of target_all, target_computer_ids, target_computer_names, or target_relevance (client relevance evaluated on each agent to decide applicability). Targeting is limited to the configured operator's scope, so target_all means all computers this operator can see, not necessarily all computers in BigFix.
Inputs: query_text (required), target_all, target_relevance, target_computer_ids, +1 more. Returns: object
find_computersFind ComputersA
Find computers whose name contains a substring.
Returns (name, id, last report time) rows. The search term cannot contain a double quote - BigFix relevance string literals have no escape for one.
Inputs: name_contains (required), limit, offset. Returns: object
find_contentFind ContentA
Search content by name across every site the operator can see.
Returns rows of {name, id, site_name, site_path} - site_path is what get_content needs. It is null when the site name is ambiguous (two sites of different types sharing a display name), with the options listed under site_path_candidates rather than guessed at.
The search term cannot contain a double quote.
Inputs: kind (required), name_contains (required), limit, offset. Returns: object
get_actionGet ActionC
Get an action's definition from /api/action/{id}.
Inputs: action_id (required). Returns: object
get_action_statusGet Action StatusA
Get an action's per-computer execution state (/api/action/{id}/status).
The "did my change actually work" tool. Status is scoped to the computers the configured operator can see.
Inputs: action_id (required). Returns: object
get_computerGet ComputerA
Get one computer's full record from /api/computer/{id}.
Includes the reported properties BigFix holds for that computer. Use find_computers first if you only know part of the name.
Inputs: computer_id (required). Returns: object
get_computer_groupGet Computer GroupA
Look up a computer group by name within an explicit site path.
Implemented against /api/computergroups/{site_path} directly rather than besapi's get_computergroup, which routes through the mutable "current site path" connection state this server avoids.
Inputs: site_path (required), group_name (required). Returns: object
get_contentGet ContentB
Get one fixlet, task, analysis or baseline by site path and ID.
Inputs: kind (required), site_path (required), content_id (required). Returns: object
get_dashboard_variableGet Dashboard VariableB
Read a BigFix dashboard datastore variable value (read-only).
Inputs: var_name (required), dashboard_name (required). Returns: object
get_operatorGet OperatorA
Look up a BigFix operator (console user) by name.
Inputs: user_name (required). Returns: object
get_server_infoGet Server InfoB
Get BigFix root server info (version, etc) from /api/serverinfo.
Inputs: no named parameters. Returns: object
list_actionsList ActionsB
List actions visible to the configured operator (/api/actions).
Inputs: no named parameters. Returns: object
list_operatorsList OperatorsA
List console operators visible to the configured operator.
Inputs: no named parameters. Returns: object
list_rolesList RolesB
List BigFix roles visible to the configured operator.
Inputs: no named parameters. Returns: object
list_sitesList SitesA
List all sites visible to the configured operator.
Returns {"data": , "truncated": ..., "total_chars": ...}. A deployment subscribed to many external content sites can produce a large listing; when it exceeds the size cap, data is null and note says so rather than handing back a half-cut structure that looks complete.
Inputs: no named parameters. Returns: object
qna_discover_targetsQna Discover TargetsA
Find qna targets that work on the server's host and add them to the inventory, like the bigfix-remote-client-relevance CLI's --auto-discovery. Evaluates nothing.
Probes this host's qna, a downloaded qna, the container engine's images and developer.bigfix.com, then adds what works and is not already listed to ~/.bigfix/remote_clients.toml. Never uses SSH discovery and never prompts. Slow: it can take minutes. Use it when qna_list_targets shows no (or too few) inventory hosts; a run of qna_eval_client_relevance naming no targets only discovers by itself when no inventory file exists yet.
Returns path (the inventory written), added (new host names) and inventory (every target now listed).
Inputs: no named parameters. Returns: object
qna_eval_client_relevanceQna Eval Client RelevanceA
Evaluate CLIENT relevance with the BigFix qna tool - a fast feedback loop that never touches the BigFix deployment.
qna runs on lab targets (containers or admin-inventoried hosts), NOT on managed BigFix endpoints: results reflect each target machine only. There is no operator scope, no site subscriptions and no client settings, so inspectors that depend on deployment state will differ from what client_query returns. Iterate on relevance syntax and inspector behavior here, then confirm on real agents with client_query.
With no inventory_targets or container_images, it runs on every inventory host (qna only reads). An online_evaluator inventory host sends the client relevance to developer.bigfix.com; name targets to keep a query off it. When no inventory file exists yet (qna_list_targets: auto_discovery_pending), such a run first discovers what works on the server's host and records it in ~/.bigfix/remote_clients.toml; once the file exists, discovery runs only through qna_discover_targets. The payload's auto_discovery says what was added. A discovering run can take minutes.
Per-target failures come back as result rows with error_kind ('relevance', 'qna', 'bootstrap', 'transport', 'resolve'), never as a tool error. ok_count and target_count describe the whole run; the rows are windowed by limit/offset.
Inputs: relevance (required), limit, offset, qna_version, +3 more. Returns: object
qna_list_targetsQna List TargetsA
List targets available to qna_eval_client_relevance.
inventory_path is the inventory file in use: BIGFIX_QNA_INVENTORY when the server sets it, else the default search (~/.bigfix/remote_clients.toml, then the all-users config directory); null when none was found. A run that names no targets uses every inventory host. auto_discovery says whether qna_discover_targets is available (it probes local qna, container images and developer.bigfix.com, and adds what works to ~/.bigfix/remote_clients.toml); auto_discovery_pending says no inventory file exists yet, so the next run naming no targets discovers first without being asked. containers_allowed says whether arbitrary container image names may be passed as targets. Listing never probes or writes anything.
Inputs: no named parameters. Returns: object
search_inspectorsSearch InspectorsA
Search the BigFix inspector reference (offline snapshot; no server call).
Fuzzy: returns exact, prefix and near-miss matches with signatures, result types and the dialect each inspector exists in. Use it before writing a query, or after an 'is not defined' error to find the right name. Snapshot caveat: absence here does not prove absence on the live server.
Inputs: query (required), kind, limit, dialect. Returns: object
session_relevance_querySession Relevance QueryA
Evaluate a BigFix session relevance query on the root server.
Session relevance queries data the server already has (computers, fixlets, actions, sites, operators...) with no client round-trip. Examples: 'number of bes computers', '(name of it, id of it) of bes computers whose (now - last report time of it < 1 * day)'.
There is no way to limit rows in the relevance itself - 'first', 'firsts', 'items' and 'elements' are all undefined operators on a BigFix root server. Use the limit/offset parameters instead; the response reports total_available and truncated. Note the server still evaluates the whole query, so limit bounds the response, not the work.
Returns the server's JSON envelope: {"result": [...], "plural": ..., "type": ..., "evaltime_ms": ...} (plus "count" when the server sends it) and bounding metadata.
Results are evaluated within the configured operator's scope. Unless whoami reports is_main_operator, counts and lists are a lower bound on what exists - report them as visible to this operator, not as the complete state of BigFix.
Inputs: relevance (required), limit, offset. Returns: object
validate_bes_xmlValidate Bes XmlA
Validate BES XML against the BigFix schemas.
Makes no server call.
Use before asking anyone to import content: it catches malformed or non-conforming XML locally instead of as a REST error.
Inputs: bes_xml (required). Returns: object
whoamiWhoamiA
Show the configured connection: user, root server, main operator status.
writes_enabled says whether the gated write tools are registered in this process; when false they are absent from the tool list entirely.
Cheap connectivity and permission smoke test. is_main_operator tells you whether results from the other tools can be treated as the full state of BigFix (master operator) or only as this operator's scoped view, which may be incomplete in ways this operator cannot detect.
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 27 tools
Most tools target a clearly distinct resource or operation (get/list/find content, computers, actions, operators, sites, qna). The main overlaps are the relevance-evaluation trio (session_relevance_query, client_query/qna_eval_client_relevance) and the client_query wrapper versus client_query_submit/client_query_results, but the descriptions explain scope and targeting differences well enough to select correctly.
Many names follow a verb_noun or qna_verb_noun pattern, but the set mixes verb-first (get_content, list_operators, find_computers) with noun-phrase names (client_query, session_relevance_query, applicable_fixlets, whoami) and noun_verb order in api_get. It remains readable thanks to clear domain prefixes, but it is not a single predictable convention.
27 tools is heavy for a single MCP server and sits above the usually comfortable 3-15 range. The BigFix root-server domain is broad (content, computers, actions, relevance, qna, server info), so most tools map to distinct subdomains, but the count is still at the borderline-heavy end.
Read coverage is fairly strong: content, operators/roles, computers, actions, sites, server info, relevance evaluation, and a read-only API escape hatch are all present. However, the surface omits action lifecycle operations (take/stop/delete action) and content import/deployment, and api_get is explicitly read-only, so the toolset cannot complete the primary BigFix management workflows.
Maintenance
Related MCP Connectors
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Official Microsoft MCP Server to query Microsoft Entra data using natural language
Read-only MCP server for ClassQuill, a tutoring-business-management platform.
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
Related MCP Servers
- AlicenseAqualityDmaintenanceA read-only MCP server for InvGate Asset Management, enabling natural language queries for assets, people, computers, servers, software, and API health.121MIT
- AlicenseAqualityCmaintenanceSecurity-first, read-only MCP server for Microsoft SQL Server, enabling safe natural-language querying of databases.59 npmMIT
- AlicenseAqualityDmaintenanceA read-only MCP server that enables AI assistants to query ServiceNow instances—incidents, changes, users, CMDB—with malformed query linting and injection protection.7MIT
- AlicenseNot gradedqualityCmaintenanceA read-only MCP server that enables natural language querying of DSpace 7+ repositories via the REST API, allowing users to search, retrieve items, and analyze repository data.38 PyPI3MIT