DOE-MCP

MCP servers over public US Department of Energy and national-laboratory data. Every answer names the systems it came from, when they were read, and what it did not cover.

Not affiliated with the US Department of Energy. DOE-MCP is an independent, community-run project. It is not endorsed by, funded by, or connected to DOE, the NNSA, any program office, any national laboratory, or any Power Marketing Administration. "DOE" names the data, not the origin. No answer this software returns is an official government statement.

DOE and its 17 national laboratories publish a large body of public data, and almost none of it is reachable over the Model Context Protocol. This project covers it by data domain over a declarative source registry, and puts a provenance envelope on every answer so a caller can check where it came from and what it does not cover.

• Use it. Install, connect a client, ask a question. The literature vertical needs no credential. See examples/README.md for workflows across all four servers.

• Contribute. The most useful contribution is a source manifest, not code. CONTRIBUTING.md has the rules for people; AGENTS.md has the ones coding agents follow.

• Understand it. design/architecture.md opens with what is built, then the system, then one record per architectural choice with the losing options kept. docs/reference.md lists every tool and argument, read back from the assembled servers.

Status

Early. Four servers work against live endpoints: the research vertical (literature, datasets, software, rulemakings, patents), the energy-data vertical (EIA, BPA, the wind and solar inventories, fuel economy), the earth server (Daymet, ESS-DIVE, the ESGF index, the Sage node inventory), and the materials server (OPTIMADE structures, basis sets). The other science domains are registry inventory with named next steps. The table below is generated from the registry the servers run on, and CI fails when it drifts. WORKLOG.md opens with the open gaps.

Related MCP server: Verilex Data

Install

Not on PyPI yet. Install from a checkout of this repository, from its root:

pipx install .

For development, with the test dependencies:

uv venv --python 3.12 && uv pip install -e ".[all]" --group dev

Then check the install and register the servers with a client:

doe-mcp doctor
doe-mcp configure claude-code        # or claude-desktop, vscode, cursor

doe-mcp configure claude-code --all registers every server at once. Where a source needs a key, it goes in your own credentials file through doe-mcp configure credentials, never into a client config.

Try it from the command line

doe-mcp tools call research.search_literature \
  --args '{"query": "perovskite tandem solar cell", "year_from": 2024, "rows": 3}'

The answer is a complete envelope: the records under data, the OSTI collections that were searched under provenance, one evidence entry per record, and coverage.pagination set to truncated, because far more matches exist than the three returned. No credential is involved.

Questions it takes

Architecture

DOE-MCP layers agent workflows over focused domain servers, typed tools, and GET-only publisher adapters:

graph TD
    User[AI Client / User] -->|Capability Walk| Skills[Skills: Task Guides]
    User -->|MCP Protocol / stdio| Servers[Domain Servers]
    Skills -.->|Composes Capabilities| Servers

    subgraph "Shipping MCP Servers (Profiles: 8-12 tools default, <=20 ceiling)"
        S1["doe-research (11 tools)<br/>literature, datasets, software, patents"]
        S2["doe-energy-data (10 tools)<br/>EIA-930 grid, BPA operations, facilities"]
        S3["doe-earth (8 tools)<br/>Daymet weather, ESS-DIVE, ESGF, Sage"]
        S4["doe-materials (7 tools)<br/>Materials Project OPTIMADE, Basis Sets"]
    end

    Servers --> S1
    Servers --> S2
    Servers --> S3
    Servers --> S4

    subgraph "Core & Adapters (Read-Only GET)"
        Registry[Declarative Registry: 83 manifests, 22 active]
        Adapters[17 Publisher Adapters: pagination, rate-limits, dialects]
    end

    S1 --> Registry
    S2 --> Registry
    S3 --> Registry
    S4 --> Registry

    S1 --> Adapters
    S2 --> Adapters
    S3 --> Adapters
    S4 --> Adapters

    Adapters -->|HTTP GET / Dialect Translation| Upstream[Public DOE, National Lab & Federal APIs]

Every response returns a structured provenance envelope:

The envelope

Every tool returns {data, provenance, evidence, coverage, warnings, ...}. The part that matters most is coverage, which has five independent dimensions that are never collapsed into one status:

{"registry": "covered", "execution": "complete", "pagination": "truncated",
 "source_claim": "partial", "result": "hit"}

result: "empty" with registry: "covered" means the searched systems hold no record. registry: "none" means DOE-MCP has no source for that question and the data may well exist. Conflating those two is the most damaging thing a government-data tool can do to someone relying on it.

DOE's additions to the inherited contract: a citation block (several publishers require citation as a condition of use), a required dataset_version (ATB 2024 and ATB 2026 are different data with the same name), typed access recipes for data too big to inline, and three warning codes for confusions this ecosystem actually produces: derived_layer, catalog_vintage, domain_migrated.

Licensing

Code Apache-2.0. The source registry under sources/ is CC0: the inventory of what exists, who stewards it, and what its terms say is more useful unencumbered. Docs CC-BY-4.0. See NOTICE.

Lineage

The packaging shape (one pip package, many focused stdio servers, the doctor/configure CLI) is borrowed with thanks from PNNL's NEPA-MCP. That project does not endorse this one.