DOE-MCP reads public publisher APIs through focused domain servers. Each answer separates the data from its sources, record evidence, access recipes, warnings and coverage. It does not operate facilities or run simulations. The source registry names unbuilt capabilities and why they cannot yet be queried.
Install from the checkout with pipx install .. The package is not yet
published on PyPI. Recorded workflows and skills ship in the wheel.
doe-mcp demo evidence --output ./evidence-run
doe-mcp demo client
doe-mcp skills
doe-mcp skills find-doe-data --show
The first command writes JSON evidence and a CSV evidence index. The second launches a real stdio server, initializes an SDK client, calls a local registry tool, validates its structured response, checks a typed error, and closes the process. Neither command needs an API key or a publisher connection.
Run doe-mcp demo --help for the list of walkthroughs. The partial case explicitly simulates one
unavailable source in an isolated replay. The blocked case reads registry
inventory; it does not query the proposed publisher.
Browse the recorded walkthroughs. Every export names its mode, registry revision, fixture hashes and available capture times. Older fixtures have no recorded capture time; those remain unknown. Envelope retrieval timestamps in a replay are a labelled fixed reference clock, never evidence of a current publisher fetch. Record dates remain separate. A captured result cannot establish current endpoint health.
doe-mcp demo evidence --live --output ./live-evidence
doe-mcp demo grid --live --output ./live-grid
Live EIA demand also requires the user’s configured EIA key:
doe-mcp configure credentials
doe-mcp demo eia --live --output ./live-demand
The grid walkthrough reports BPA load in MW and the publisher’s Pacific Time labels. EIA reports hourly energy in MWh. Neither series establishes local connection capacity. Keep forecasts distinct from observations.
The site walkthrough plots a bounded sample of Rhode Island facility coordinates. The plot extent is the returned sample’s extent, not a parcel search. Ownership, queue position, tariffs and available capacity remain unknown. Its NEPA-MCP link is a manual handoff to another project.
Earth search results and Oak Ridge modelled weather are separate examples, not a claimed study-site match. The materials walkthrough likewise keeps the computed GaN structure separate from the H/C/O basis-set example.
The facility-status tool has checked skill tasks but no walkthrough page yet; the examples show one call for each. Outage history returns the EAGLE-I release that covers a year and its DOI, not outage figures. The microbiome tools return study and sample metadata; sequence data stays behind each study’s DOIs.
DOE’s Genesis Agent Skills release provides scientific workflow instructions. DOE-MCP’s own skills now use the same Agent Skills format. This is format compatibility, not an installed connection to the upstream catalog or a claim of DOE endorsement.
Use doe-mcp skills NAME --show to read an installed walk. The names
below are local DOE-MCP skills. Each points to the specific upstream guide
it draws on and has a bench that checks results from recorded data.
| Installed DOE-MCP skill | Genesis method | Recorded result |
|---|---|---|
genesis-build-bibliography |
literature-search | Citation worksheet with omitted author counts. |
genesis-draft-dataset-card |
datacard-generator | Geothermal metadata draft with file integrity, rights and sensitivity left for the owner. |
genesis-package-weather-data |
croissant-validator | Daymet CSV and Croissant metadata with a checksum for the exported bytes. |
genesis-audit-sample-fields |
data-exploration | Soil metadata audit with missing-field counts on the returned page. |
genesis-score-load-errors |
uq-metrics-evaluator | BPA baseline errors with mean absolute and root mean squared error in MW. |
genesis-check-prediction-bands |
uncertainty-quantification | Prediction band worksheet with separate calibration and evaluation rows. |
For example:
doe-mcp skills genesis-check-prediction-bands --show
doe-mcp demo load-interval-check --output ./bpa-band
Use the worksheet to trace each prediction to its prior and target readings. The earlier errors set the width once. The later rows show whether the actual load landed inside the band. For the dataset card, the draft contains only catalog evidence; no file is downloaded or inspected and the card has not been validated against the Genesis schema.
The microbiome example follows microbiome-data-finder: search NMDC for
shale studies, then use a returned study ID to request five biosamples.
The page shows the sample’s place, collection date and environment.
Publisher access recipes retain the distinction between dataset and award
DOIs. The workflow does not retrieve sequence data or infer biological
function.
For a citation list, run doe-mcp demo bibliography --output ./citations.
Open bibliography-worksheet.csv to check dates, DOIs and omitted authors.
For a count of missing soil sample measurements, run
doe-mcp demo soil-metadata --output ./soil. In
soil-metadata-worksheet.csv, the depth check counts a value or either end of a range in metres. The last column of each worksheet identifies the
evidence entry in step 1 of its JSON report. See the
comparison with other government-data MCPs
for the reasons behind these checks.
These examples default to recorded responses with no network or model calls. Except for the recorded Daymet package, add
--live for public API reads without a key; availability and results can
change. Downloading the underlying datasets may have separate conditions.
An AI client chosen by the user may charge for inference, but these CLI
examples and the static previews do not require one.
To use the skills conversationally, give a compatible client the installed skill file and a bounded request: “Find two geothermal dataset records and list missing documentation fields” or “Find a shale study and five linked biosamples; state what was not retrieved.” Model output still needs review; the deterministic demonstrations do not measure agent accuracy.
The upstream Genesis catalog also covers facility operations, data movement and model services. Public skill files do not grant an allocation, an account, free inference or permission to transfer data. These demos execute none of that upstream code.
doe-mcp configure claude-code research --dry-run
doe-mcp configure claude-code research
The other supported configuration targets are claude-desktop, vscode
and cursor. Start with the domain you need. Registering all servers also
loads a larger combined tool set into clients without deferred discovery.
Credentials stay in the user’s credentials file, outside client configs.
doe-mcp skills NAME prints the installed file path. Ask a client that can
read local files to read that file before starting the task, or provide
its content from --show. Skills are packaged documents; they are not
loaded automatically as MCP resources or installed as client plugins.
The fetcher supports GET only. Source gates check registry eligibility before a publisher is queried. Adapters interpret each publisher’s response; domain tools assemble the evidence envelope; MCP serves its typed shape.
Coverage has separate dimensions: registry, execution, pagination, publisher scope and result. A hit does not imply a complete search. An empty result does not establish that DOE has no data. A proposed source in the registry does not contribute live evidence. Follow publisher-supplied locators; never construct a plausible record URL from an identifier.
The JSON export keeps each call, its arguments and its envelope. CSV is an evidence index, not a substitute for JSON’s coverage and warnings. Each CSV row names its workflow step, source and record. Potential spreadsheet formula cells are escaped.
See the generated tool reference for exact names and
arguments. The static site is generated by tools/build_site.py; change
its renderer or registry inputs, not generated pages.
Prepare the existing skill tasks without calling a model:
doe-mcp evaluate --prepare --output ./evaluation-tasks.json
The twelve cases cover useful answers and six traps. Evaluation annotations
live beside the checked and reader tasks in each skill’s bench.yaml.
Contract tests run offline. They do not prove model-selection accuracy.
Optional model runs use an explicitly supplied executable driver:
doe-mcp evaluate --driver ./model-driver --model YOUR_MODEL \
--max-calls 12 --max-tokens 20000 --repeats 3 \
--exposure focused --output ./evaluation-run.json
The driver reads one JSON request on stdin and writes one JSON response on
stdout. The request carries messages, visible tool schemas, a remaining
token budget and an output-token limit. The driver calls the chosen model
and returns either tool_calls (name and arguments) or answer (text and
citations), plus actual usage.input_tokens and usage.output_tokens. Return
model_version and settings to identify the model and sampling
configuration; absent values are explicitly reported as unknown.
Each citation names a one-based tool step and an evidence ID from that
step. Keep provider credentials in the driver’s own environment; never
return them or log them. Driver stderr is not retained.
The harness executes requested tools against recorded responses. It refuses unavailable tools and stops after a driver failure or unknown usage. The call cap is enforced before each request; token accounting relies on the driver, which must enforce the remaining total budget at the provider. A provider call cannot be unspent when a driver over-reports its budget. No paid model driver is bundled or run by default.
Run focused/all tool exposure with skills enabled/--no-skills, three
repetitions each. Cases not run because of a budget remain in the report’s
denominator. Reports preserve failures and require human review against
each task’s rubric. Automatic citation checks are not semantic grading;
no accuracy score is advertised before that review. Source text is
untrusted, including the injected-instruction trap.
For a release, require no fabricated locators, leaked keys, forecast-as- demand claims or invented source coverage. Inspect all trap answers and report numerator and denominator for useful-task success. The architecture’s 90% target is a proposed small-sample release gate, not a measured result.
python -m pytest
ruff check .
mypy
doe-mcp sources validate
python tools/build_schema.py
python tools/build_site.py --fixtures
python3 tools/slopcheck.py --include-agent-docs .
Measure local replay overhead separately from model or publisher latency:
python tools/benchmark_workflows.py --output ./replay-baseline.json
This records three cold/warm pairs per workflow, startup time and output
bytes. It makes no claim about live performance. CI also builds a wheel
from a source distribution and runs tools/check_installed.py in a clean
environment outside the checkout.
The initial type-check scope is the envelope and OSTI page adapter. It is
not a claim that the whole project is typed. Source liveness remains a
separate scheduled check. Fixture recording rewrites a whole source file;
use the existing recorder guards and run the full suite immediately after
recording. A targeted recording uses --source SOURCE_ID.
doe-mcp demo rulemaking --output ./rulemaking-brief searches a recorded
Federal Register page and follows one returned DOE document number.
The table keeps the publisher action and publication, effective and
comment-close dates separate. Unknown dates stay unknown. FERC documents
are excluded, and the publisher total still includes those exclusions.
This is document metadata, not a legal-status assessment or a full docket.
Add --live for a current search; no key or model is required.
doe-mcp demo outage-history --output ./outage-history finds the EAGLE-I
release covering 2021 and presents its DOI, documentation and the separate
customer-count dataset. This locates files; it does not download county
measurements or compute an outage rate. The denominator’s vintage is shown
in its publisher title, because mixing years can mislead. Customers are
not people, and publisher coverage is incomplete. Add --live to check
the public catalog without a key or model.
The missing Daymet date follows one grid cell near Oak Ridge from December 26 through December 31, 2024. The temperature CSV ends on December 30. Daymet’s calendar has 365 days, including in leap years. The download contains no row for December 31.
Run doe-mcp demo daymet-calendar --output ./daymet or download the
temperatures CSV and Croissant metadata into the same directory.
The metadata describes this recorded extract, gives the source citation
and maps each field to a CSV column. Its SHA-256 digest covers the
downloaded CSV. The underlying Daymet archive has its own
data use guidance.
With the optional MLCommons reader installed, read the five rows:
from mlcroissant import Dataset
days = Dataset("daymet/daymet-calendar-croissant.json").records("days")
for day in days:
print(day["days/date"], day["days/tmax_deg_c"])
The BPA load worksheet uses the last reported load as a prediction for the next five minutes. For example, the recording starts at 5,894 MW. Five minutes later BPA reported 5,832 MW, so the first prediction was 62 MW high.
Run doe-mcp demo load-baseline --output ./bpa. The worksheet CSV shows
each prediction beside the later reading and identifies both pieces of
evidence in the JSON. The mean absolute error gives each miss its size in
megawatts. The root mean squared error gives larger misses more weight.
Both scores use only pairs five minutes apart with load at both ends.
These are retrospective scores for this sample. BPA did not issue the
predictions. Add --live to score a new window from the public feed.