ferc-eqr

Who sells wholesale power to whom: FERC Electric Quarterly Report (EQR) filers, and the contracts between sellers and their counterparties.

Part of Pipeworx — an MCP gateway connecting AI agents to 1679+ live data sources.

Not the same thing as ferc-elibrary: that pack is FERC's docket/document search (filings, orders, opinions). This pack is the underlying filer and contract data — a different question entirely ("who sells to whom" vs. "what did FERC file").

Tools

Tool	Answers
eqr_seller_lookup	Resolve a company name or FERC company id (e.g. "C000740") to its EQR filer record(s) — per-quarter filings and whether the filer reported transactions to an index price publisher. Company-level identity only, no filer contact details.
eqr_contracts_search	Search contracts by seller, counterparty and/or product, with a quarter range. Returns contract-level rate-period line items — quantity, rate, delivery/receipt points, term dates.
eqr_counterparty_sellers	"Who sells power to X" — sellers aggregated for a counterparty name match, with contract counts and the quarter range they appear in.
eqr_coverage	Row counts per table, the quarter range currently covered, and when it was last refreshed. Call this before treating an empty result as a negative answer.

Auth

None. No key, no account.

No personal data

The upstream source also carries filer CONTACT fields per company — a named individual's name, title, address, phone and email. None of that is loaded or returned by any tool. Only company-level identity (company_id_ferc, filer_unique_id, company_name) is kept.

Coverage is not automatically "everything since 2013"

The upstream data spans 2013q3 through the present, but this pack's coverage is loaded incrementally rather than all at once. Call eqr_coverage for the quarter range actually covered before treating an empty result as "no such contract" — a result outside the covered range is a coverage gap, not a negative answer. Every tool's response says this too.

Data source, licence, attribution

FERC itself publishes Electric Quarterly Reports only as quarterly nested ZIP files, with no query interface of its own. Catalyst Cooperative's PUDL project — a widely-used open energy-data project — normalizes EQR into structured per-quarter tables and republishes them publicly.

Licence: "Copyright 2016-2026, Catalyst Cooperative, CC-BY-4.0" (https://docs.catalyst.coop/pudl/en/latest/LICENSE.html) — explicit on the DATA (their processing code carries a separate MIT licence, which is a different thing and does not govern the data). CC-BY-4.0 permits redistribution with attribution. Every tool response carries an attribution field; do not remove it if you touch this pack.

Refreshing

node scripts/ingest-ferc-eqr.mjs --since <yyyyqN>

Re-runnable and safe: rows upsert on a content hash of every loaded column, so loading an already-covered quarter again is a no-op rather than a duplicate. node scripts/ingest-ferc-eqr.mjs --dry-run [--since <q> | --all] parses without writing anything, useful for checking a new quarter's row counts before committing to a load. listQuarters() discovers what's published live each run, so a newly published quarter needs no code change — just a wider --since.

Phase 1 vs Phase 2

Phase 1 (this pack): filer identity, index-price-publisher reporting, and contract terms — one row per contract RATE-PERIOD line item, not one row per contract (a single contract can carry several rows for different rate periods over its life). A quantity or rate returned here comes from the CONTRACT's stated terms, not from a settled trade.

Phase 2 (not built): the actual settled trade-level price/volume data — what a contract's terms say vs. what was actually transacted. By far the most valuable data for a "what did seller X actually sell at what price" question, and by a wide margin the hardest: the upstream source for it is roughly two orders of magnitude larger than everything Phase 1 covers, and a single recent quarter alone is larger than this pack's entire current coverage. It needs a different loading strategy than Phase 1's — most likely a narrower rolling window rather than full history, or a different storage shape entirely. Not filed as a task; scope it separately once real demand for Phase 1 is measured (does anyone actually call eqr_contracts_search / eqr_counterparty_sellers), because its infrastructure cost is substantial enough to want that evidence first.

Quick Start

Add to your MCP client (Claude Desktop, Cursor, Windsurf, etc.):

{
  "mcpServers": {
    "ferc-eqr": {
      "url": "https://gateway.pipeworx.io/ferc-eqr/mcp"
    }
  }
}

What this endpoint actually serves

tools/list at https://gateway.pipeworx.io/ferc-eqr/mcp returns the tools in the table above plus the shared Pipeworx meta-tools — ask_pipeworx, discover_tools, search_within, remember/recall and the rest of the gateway-wide set. So the tool count you see is larger than this table: a single-pack endpoint currently lists roughly 30 shared tools alongside the pack's own. The connection's initialize response states its exact scope, and is the authoritative answer for a given day.

This is deliberate, not multiplexing by accident. The meta-tools are what let a scoped connection answer a question this pack does not cover — via ask_pipeworx, which routes across the whole catalog — without you adding a second MCP server. There is currently no way to mount a pack endpoint without them; if the extra schemas cost you more context than the routing is worth, connect to the full gateway once rather than to several pack endpoints.

Or connect to the full Pipeworx gateway to get every pack's tools listed directly, instead of just this one's:

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

Both URLs reach the same gateway and the same 1679+ data sources. The only difference is which pack's tools are listed directly; ask_pipeworx reaches all of them from either one.

No MCP client? Call it over HTTP

curl -X POST https://gateway.pipeworx.io/v1/tools/eqr_seller_lookup \
  -H 'Content-Type: application/json' \
  -d '{"query":"NextEra"}'

No account needed for the first calls. Inspect any tool: GET https://gateway.pipeworx.io/v1/tools/eqr_seller_lookup. Find one: POST https://gateway.pipeworx.io/v1/tools/search_packs with {"query":"..."}.

Standalone (no gateway account)

This package also runs as a local stdio MCP server — no Pipeworx account, no gateway round-trip:

{
  "mcpServers": {
    "ferc-eqr": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-ferc-eqr"]
    }
  }
}

Or run it directly to confirm it starts:

npx -y @pipeworx/mcp-ferc-eqr

It speaks MCP over stdin/stdout and answers initialize/tools/list/tools/call for only this pack's tools — none of the shared meta-tools the gateway connection above adds. Same source, same tools, no ask_pipeworx routing.

Using with ask_pipeworx

Instead of calling tools directly, you can ask questions in plain English — this works on the pack endpoint above as well as on the full gateway:

ask_pipeworx({ question: "your question about Ferc Eqr data" })

The gateway picks the right tool and fills the arguments automatically.

More

• Docs and guides
• pipeworx.io

License

MIT