OilPriceAPI
OfficialSummary: An MCP server that gives AI clients source-timestamped oil, gas, LNG, carbon, marine fuel, and related energy data and analytics from OilPriceAPI (limited keyless demo; broader catalog with an API key).
Spot prices — latest price for a single commodity (natural language or codes), side-by-side comparison of 2–5 commodities with spread, and an account-wide market overview grouped by category (oil, gas, coal, refined, metals, forex).
Catalog discovery — list the account-visible commodity codes, with suggestion-bearing errors for unrecognized names.
History — high/low/avg/change over day/week/month/year, with point-in-time
as_offiltering.Futures — front-month prices and full forward curves with contango/backwardation structure for Brent, WTI, gasoil, TTF, JKM, and carbon.
Marine fuels — bunker prices (VLSFO, MGO, IFO380) filtered by port name or UN/LOCODE, with as-of age and stale flags.
Natural gas — US physical hub prices with basis to Henry Hub and optional basis history.
Spreads — crack (e.g., 3-2-1), basis, and blending/transport margins.
Upstream activity — US rig counts, drilling snapshot (US/Canada/international rigs, frac spreads, 30-day permits, DUCs), well permits (latest/by state/by operator, state-scoped search, API-number lookup, recent activity trends).
Well production (beta) — national/state summaries, per-well monthly history, top producers, cycle times, and spud cohorts.
Diesel & freight costs — AAA retail diesel by state (50 + DC) and carrier-published LTL/parcel fuel surcharges with history.
Supply & inventories — Cushing and SPR storage, EIA weekly petroleum stocks, and OPEC country production.
Forecasts — EIA STEO and other energy price outlooks.
Data trust signals — OilPriceAPI's own data-quality grades per series and operational service health.
Account & commercial info — plan tier, usage/quota/reset date, and live plan pricing to explain entitlements and upgrade paths.
Product facts — a keyless, versioned contract describing the API's offer, freshness, auth, entitlement, and data-rights terms.
Market brief — multi-commodity snapshot with 24h changes, 1-month forecasts, spreads, and optional plain-English narrative.
Alerts & watches — list persistent price alerts and their recent triggers, list subscriptions, and poll subscription events via a
sincecursor (create/delete tools require explicitly enabled write scope).Guardrails — read-only by default, smart errors with suggestions, and machine-readable 402/403/429 responses pointing to upgrade paths.
Provides energy commodity data and analysis tools for Codeium's Windsurf IDE, enabling access to oil, gas, and commodity prices and market intelligence within the development environment.
This server has a remotely hosted endpoint. Open its connector listing for connection details, authentication requirements, and setup instructions:
OilPriceAPI MCP Server
Give compatible AI clients source-timestamped oil, gas, LNG, carbon, fuel, and related energy data through MCP. No API key is needed to try the limited demo.
Get a Free API Key · Documentation · API Explorer · Pricing
Backed by OilPriceAPI, a normalized REST API for energy dashboards, fleet and logistics tools, maritime workflows, and market research.
Canonical sources: Public product facts · Official MCP Registry record
Features
Reviewed product facts — a keyless read-only tool and stable resource for offer, freshness, authentication, catalog, entitlement, and data-rights questions
Data and workflow tools — latest values, history, futures, marine fuels, fuel surcharges, energy intelligence, alerts, market briefs, and persistent watches
Resources — the reviewed product contract plus subscribable price snapshots
Prompts — analyst templates for briefings, spread analysis, gas markets, diesel costs, and supply analysis
Natural language — ask for "brent oil" or "natural gas", not codes
Broad catalog — oil, gas, coal, refined products, metals, forex, bunker fuels, state diesel, and selected energy-intelligence datasets; access varies by plan and account
Smart errors — unrecognized commodities get suggestions, not silent fallbacks
Related MCP server: fuel-prices
Quick Start
npx oilpriceapi-mcpThe default scope is read-only. Account mutations are not listed and direct mutation calls are rejected unless write scope is explicitly enabled:
npx oilpriceapi-mcp --scope writeInspect the package without opening an MCP stdio session:
npx oilpriceapi-mcp --version
npx oilpriceapi-mcp --list-tools
npx oilpriceapi-mcp --list-tools --json --profile core
npx oilpriceapi-mcp doctor --demo
npx oilpriceapi-mcp doctor
npx oilpriceapi-mcp --capabilities --json
npx oilpriceapi-mcp --config claude-code
npx oilpriceapi-mcp --config vscode--config generates client-native, copy/paste-valid JSON for
claude-desktop, claude-code, cursor, vscode, cline, or windsurf.
It never reads or prints the configured API key. Claude Code, VS Code, and
Windsurf outputs use their supported environment or secure-input references;
Claude Desktop, Cursor, and Cline use an explicit local replacement marker.
Add --demo to omit API-key configuration entirely. Scope, profile, and
category options are preserved in the generated server arguments.
What can your agent get?
Example commodity codes:
Code | What it is | Typical agent use |
| Brent crude (global) | market briefings, dashboards |
| WTI crude (US) | trading context, macro models |
| Henry Hub natural gas | energy analytics |
| TTF gas (Europe) | European energy, LNG analysis |
| JKM LNG (Asia) | LNG trading & shipping |
| EU ETS carbon allowances | CBAM, maritime compliance, ESG |
| Diesel (Gulf Coast) | fleet & fuel-surcharge math |
| Jet fuel | aviation ops |
| Marine bunker fuel | voyage costing |
| Gold | macro & portfolio context |
Installation
Try it without an API key
The server works out of the box in keyless demo mode — just omit OILPRICEAPI_KEY from the configs below. The price tools (opa_get_price, opa_compare_prices, opa_list_commodities, opa_market_overview) serve latest available values for a limited demo commodity set, and every other data tool explains its account requirements. Demo responses are marked with a footer. For the broader account-enabled catalog, history, futures, and alerts, get a free API key and add it to your config.
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"oilpriceapi": {
"command": "npx",
"args": ["-y", "oilpriceapi-mcp"],
"env": {
"OILPRICEAPI_KEY": "your-api-key-here"
}
}
}
}Claude Code
Add to your project's .mcp.json:
{
"mcpServers": {
"oilpriceapi": {
"command": "npx",
"args": ["-y", "oilpriceapi-mcp"],
"env": {
"OILPRICEAPI_KEY": "your-api-key-here"
}
}
}
}Cursor
Add to .cursor/mcp.json in your project root:
{
"mcpServers": {
"oilpriceapi": {
"command": "npx",
"args": ["-y", "oilpriceapi-mcp"],
"env": {
"OILPRICEAPI_KEY": "your-api-key-here"
}
}
}
}VS Code + Cline
Add to .vscode/mcp.json:
{
"servers": {
"oilpriceapi": {
"type": "stdio",
"command": "npx",
"args": ["-y", "oilpriceapi-mcp"],
"env": {
"OILPRICEAPI_KEY": "your-api-key-here"
}
}
}
}Windsurf
Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"oilpriceapi": {
"command": "npx",
"args": ["-y", "oilpriceapi-mcp"],
"env": {
"OILPRICEAPI_KEY": "your-api-key-here"
}
}
}
}Global Install
npm install -g oilpriceapi-mcpBuild the Container
Container builds require the source revision and commit timestamp so the image, capability manifest, and build metadata are traceable to the same checkout:
docker build \
--build-arg SOURCE_COMMIT="$(git rev-parse HEAD)" \
--build-arg SOURCE_DATE_EPOCH="$(git show -s --format=%ct HEAD)" \
-t oilpriceapi-mcp .
docker run --rm oilpriceapi-mcp --version
docker run --rm oilpriceapi-mcp --capabilities --jsonThe runtime image uses the unprivileged node user. Omit OILPRICEAPI_KEY for
the limited keyless demo, or inject it with your container platform's secret
manager. Do not bake credentials into the image.
Transport
This server runs locally over stdio only. Its MCP Registry record lists the npm package and no remote endpoint.
The hosted connector at https://mcp.oilpriceapi.com/mcp is not this server.
It is a separate, smaller set of energy_* tools with OAuth account linking,
used by hosted clients that cannot launch a local process. Use this package for
the full opa_* tool set. The hosted connector has its own MCP Registry
record, io.github.OilpriceAPI/hosted-energy, defined in server.hosted.json
and published by the manual registry-hosted.yml workflow.
Environment Variables
Variable | Required | Description |
| No | API key from oilpriceapi.com/auth/signup. After the core trial, use the public product facts or your account response for the current Free allowance and reset window. Dataset access and limits vary by plan and entitlement. Without a key, the server uses the limited demo. |
| No | Override API base URL (for staging/testing). Default: |
| No |
|
| No | Stable inventory profile: |
| No | Comma-separated category allowlist ( |
Tool Scope and Profiles
read scope includes all non-mutating tools, including alert history,
subscription listing, and subscription event polling. The four create/delete
tools require --scope write or OILPRICEAPI_MCP_SCOPE=write. Unknown scope,
profile, or category values fail closed before stdio starts.
Profiles reduce tool overload without replacing first-class MCP actions:
Profile | Included categories |
| core, market, automation |
| core |
| core, market |
| core, automation |
For example, a read-only price and product-facts server can use:
{
"command": "npx",
"args": ["-y", "oilpriceapi-mcp", "--scope", "read", "--profile", "core"]
}Doctor and Capability Contract
doctor checks the Node runtime, package entry point, API reachability, key
validity, current plan, and reported feature gates. doctor --demo performs a
bounded keyless request. Failures distinguish missing configuration, 401, 402,
403, 429, timeout, DNS/TLS, and upstream 5xx responses. The API key is never
printed.
Every package includes build/capabilities.json. It is generated from the same
SDK registry used by tools/list and records the package/version/source commit,
minimum Node version, scopes, profiles, exact inventories, per-tool annotations,
key/entitlement requirements, resources, commands, and support URLs. Website and
docs consumers should pin a package version, validate schemaVersion and
sourceCommit, and update the artifact only through an explicit dependency
upgrade. They should not scrape CLI prose or hard-code tool counts.
API-to-MCP capability ledger
capability-ledger.json records an explicit decision for every operation in
the published OilPriceAPI contract (https://api.oilpriceapi.com/openapi.json).
Each operation is either exposed, naming the registered tool(s), or
not_exposed with a disposition (selected, deferred, alias,
unsupported, internal) and a one-line reason. Families group operations into
workflows, including preview API families the server calls that are not in the
canonical contract yet.
npm run build && npm run check:capability-ledger compares the ledger with the
live contract, build/capabilities.json and the REST paths src/index.ts
calls. It exits 1 on drift, such as a new API operation with no decision, a
removed one, or an unrecorded tool or path. It exits 2 when it cannot check: the
contract is unreachable, the build manifest is missing, or the route-policy
snapshot is older than its stated threshold. CI runs it on every pull request
and daily. When a decision changes, bump ledgerVersion, append to changes,
and link that change from the release notes.
Tools
All tools are prefixed with opa_ to avoid name collisions when multiple MCP servers are loaded.
Tool | Description |
| Reviewed product, offer, freshness, auth, integration, entitlement, and data-rights contract |
| Current spot price for a single commodity |
| Account-visible current prices returned by the API, grouped by category |
| Side-by-side comparison of 2-5 commodities with spread |
| Account-visible commodity catalog returned by the live API |
| Historical prices with high/low/avg/change (day/week/month/year) |
| Dated price rows for 1-5 commodities over a start/end date range, hourly to monthly, paged |
| Front-month futures (Brent, WTI, gasoil, TTF, JKM, EU carbon) |
| Full forward curve with contango/backwardation analysis |
| Brent, WTI, NYMEX natural gas, ICE gasoil OHLC history per contract month, up to 730 days |
| Continuous front-month Brent or WTI daily/weekly/monthly bars (revisable snapshots, not settlements) |
| Bunker fuel prices by port and fuel type (VLSFO/MGO/IFO380) |
| Bunkering port directory (UN/LOCODE, region, fuel services) or one port with recent prices |
| Daily history of one marine fuel at one port; paid subscription or active trial |
| Baker Hughes US total rig count with region and observation date |
| Drilling snapshot: rig counts, frac spreads, 30-day permits, DUCs |
| AAA retail diesel price for any US state (50 states + DC) |
| LTL and parcel carrier fuel surcharge percentages with effective dates and source provenance |
| Your own surcharge schedule (percent or per mile) applied to the EIA weekly diesel index |
| Cushing and SPR oil storage/inventory levels |
| OPEC country-level production data |
| EIA STEO energy price forecasts |
| EIA weekly petroleum stocks (latest/summary/by_product) |
| Scheduled BLS, EIA, Fed, OPEC and Baker Hughes releases over 1-90 days, with calendar coverage |
| US well drilling permits (latest/by_state/by_operator) |
| State-scoped permit search by county/operator/date with measured freshness gate |
| Paged permit records across states and a permit-date range; Well Permits subscription |
| Up to 25 recent permits for one state over 1-90 days, with as-of date; any API key incl. Free |
| API-number lookup with promoted lifecycle and exact monthly production when available |
| Recent permit counts/top operators/trends with explicit state-health warnings |
| US well production — beta coverage (summary/states/state/well/top_producers/cycle_time/cohorts) |
| Crack (type, crude), basis (pair, or all pairs), margin (index); optional date-range history |
| Z-score, percentile and volatility of the latest price vs its trailing window; plan-gated |
| Trend, RSI, SMA, support/resistance and signal, or one indicator series; plan-gated |
| Correlation of two commodities (rolling series) or a matrix of up to 10; plan-gated |
| Named basis/crack/ratio spread vs its trailing distribution, or its daily series; plan-gated |
| US physical gas hub prices as basis to Henry Hub (Waha, SoCal, Chicago and more) |
| EIA weekly Lower 48 working gas: level, change, year-ago, five-year average; plan-gated |
| OilPriceAPI's own data-quality grades per series (completeness, freshness and more) |
| OilPriceAPI's own operational health by component and update tier; no API key needed |
| Plan tier, request usage, remaining quota and reset date for the configured key |
| Current subscription plans: price, request limits and included features |
Price Alert Tools (authenticated)
These tools create and manage persistent price alerts tied to your OilPriceAPI account, so they require an API key (OILPRICEAPI_KEY). The alert engine evaluates eligible source updates and notifies you (by email, plus webhook if you provide one) when a condition is met.
Tool | Description |
| Create a persistent alert (commodity, operator, threshold, optional webhook) |
| List all alerts on the account |
| Permanently delete an alert by id |
| Recent alert trigger activity (optionally filtered by |
| Dry-run one alert against the latest price (would it trigger, cooldown) |
Market Brief & Subscription Tools (authenticated)
The market brief gives a multi-commodity snapshot in one call. Subscriptions ("watches") are persistent, recurring snapshots tied to your account — the API records an event every interval, and the agent polls for new events via a per-user cursor (events are polled, not pushed — there is no always-on connection). These require an API key (OILPRICEAPI_KEY). A subscription differs from an alert: a watch always emits an event each interval (a running log), whereas an alert fires only on a threshold crossing. Per-account code, watch, and cadence limits apply; the API response is authoritative and returns the current limit when exceeded.
Tool | Description |
| Multi-commodity brief: prices, 24h changes, 1m forecasts, spreads, optional narrative |
| Create a persistent recurring watch (codes, interval like |
| List all subscriptions on the account |
| Permanently delete a subscription by id |
| Poll for new watch events since a cursor ( |
Example Questions
"What's the current Brent oil price?"
"Compare Brent and WTI crude"
"Show me oil prices for the past month"
"What's diesel cost in California vs Texas?"
"Give me a market overview of refined products"
"What's the Brent futures curve look like?"
"How many rigs are active in the US?"
"What are OPEC production levels?"
"What are bunker fuel prices in Singapore?"
"Show me Cushing storage levels"
"What were the latest EIA crude oil inventories?"
"How many well permits were issued in Texas?"
"What's the current 3-2-1 crack spread?"
"What's the UPS ground fuel surcharge?"
"Show me the gasoil futures curve"Resources
Subscribable price data (JSON):
Resource | URI | Description |
Product Facts |
| Reviewed, versioned public product contract |
Brent Crude |
| Global benchmark crude oil price |
WTI Crude |
| US benchmark crude oil price |
Natural Gas |
| US Henry Hub natural gas price |
Diesel |
| US national average diesel price |
Market View |
| Account-visible current prices from the API |
Product Facts and Model Knowledge
opa_get_product_facts and oilpriceapi://product-facts improve accuracy for a connected MCP session. They do not retrain a model or update its general knowledge. The server prefers the canonical keyless contract, uses a bounded cache, and labels any checksum-verified package fallback with source and warning metadata.
Prompts
Pre-built analyst templates:
Prompt | Description |
| Energy market daily briefing with key prices and movers |
| Analyze the Brent-WTI crude oil spread |
| Compare US vs European natural gas markets |
| Detailed report on a specific commodity (parameterized) |
| Compare diesel prices across US states for fleet planning |
| Analyze supply using OPEC production, rig counts, storage |
Natural Language Support
You say | We understand |
"brent oil", "brent crude" | BRENT_CRUDE_USD |
"wti", "us oil" | WTI_USD |
"natural gas", "henry hub" | NATURAL_GAS_USD |
"european gas", "ttf" | DUTCH_TTF_EUR |
"diesel" | DIESEL_USD |
"gold" | GOLD_USD |
"jet fuel", "aviation fuel" | JET_FUEL_USD |
"carbon", "carbon credits" | EU_CARBON_EUR |
Development
npm install
npm run build
npm test
OILPRICEAPI_KEY=your-key node build/index.jsBreaking Changes in v3.0.0
The default tool scope is now read-only. Create/delete alert and subscription tools require explicit
--scope writeorOILPRICEAPI_MCP_SCOPE=write.Invalid scope/profile/category configuration now fails before MCP stdio starts.
Use
--list-tools --jsonor--capabilities --jsoninstead of relying on a hard-coded inventory.
Breaking Changes in v2.0.0
All tool names now use
opa_prefix (e.g.,get_commodity_price->opa_get_price)Unrecognized commodity names now return an error with suggestions instead of silently defaulting to Brent
list_commoditiesnow fetches live from the API (falls back to static list if unavailable)
The whole OilPriceAPI toolbox
Same data, every stack:
Tool | Install |
| |
| |
| |
| |
no-code price widgets |
Explore the API
🧭 Interactive explorer: api.oilpriceapi.com/swagger — try every endpoint in the browser (demo mode, no key needed)
📜 OpenAPI spec: swagger.json
Privacy Policy
This MCP server runs locally on your machine and only communicates with the OilPriceAPI service:
What is sent: tool requests are translated into HTTPS calls to
api.oilpriceapi.com(commodity codes, query parameters such as time period or state, carrier slugs and service-level inputs for fuel surcharges, and — for alert/subscription tools — the alert parameters you specify), authenticated with your API key. No conversation content is transmitted — only the structured tool inputs above.API key storage: your key is stored locally in your MCP client's configuration (or the
OILPRICEAPI_KEYenvironment variable). It is sent only toapi.oilpriceapi.comas an Authorization header.Logging and demand telemetry: each tool emits a local structured hit/miss event to stderr and attributes its API request with the tool name plus a deliberately lossy argument shape. Commodity codes, intervals, state codes, and bounded numeric controls may be retained; free text, prompts, names, IDs, API well numbers, coordinates, and thresholds are reduced to
provided. API request logging follows the OilPriceAPI Privacy Policy.Third parties: no data is shared with third parties beyond what that policy describes.
Demo mode: without an API key, price tools call the keyless demo endpoint on the same host; no key or account data is involved.
Questions: support@oilpriceapi.com
Pricing Boundary (HTTP 402)
Where the free/paid line sits for this server (#10):
Always open: the MCP server itself (MIT), setup, docs, discovery (tool listing), and keyless demo mode for low-volume evaluation.
API key: use the public product facts and your account response for the current trial, allowance, reset window, and dataset entitlement. Keyless demo mode remains available for a limited dataset.
Behind the paywall: high-volume usage and premium datasets (futures, energy intelligence, well permits/production, alerts at scale). When a request crosses that boundary the API returns a standard HTTP 402/403/429 with the exact limit or feature gate in the body, and this server surfaces that message plus an upgrade link — agents get a machine-readable stop, never a silent failure.
x402 protocol: per-request crypto micropayments via the x402 protocol are not currently supported — payment is by account plan (Stripe), authenticated with your API key.
License
MIT
Links
Also Available As
Python SDK - Python client with Pandas integration
Node.js SDK - TypeScript/JavaScript SDK
Go SDK - Idiomatic Go client
OpenBB Integration - OpenBB Platform provider
Available Tools
32 toolsopa_compare_pricesCompare Commodity PricesARead-onlyInspect
Compare current prices between 2-5 commodities side by side. Use when the user asks to compare commodities (e.g., 'Brent vs WTI', 'US gas vs EU gas'). Returns each commodity's price with 24h changes, plus the spread if comparing two same-currency commodities. Accepts natural language or codes.
Inputs: commodities (required).
opa_get_account_statusGet Account StatusARead-onlyInspect
Get the current API account's plan tier, request usage, remaining quota, and reset date. Use before calling gated tools, when the user asks about their plan/limits/usage, or after any 402/403/429 to explain what the current plan covers. Works on every plan including free.
Inputs: no named parameters.
opa_get_alert_triggersGet Alert TriggersARead-onlyInspect
Get recent trigger activity for the user's price alerts — which alerts have fired, how many times, and when they last triggered. Use when the user asks whether any alerts have gone off or about recent alert activity. REQUIRES an API key (OILPRICEAPI_KEY). Note: the API tracks trigger history as per-alert counters (trigger_count / last_triggered_at) rather than a separate event feed, so this returns alerts that have triggered.
Inputs: since.
opa_get_data_qualityGet Data Quality ReportARead-onlyInspect
Get OilPriceAPI's own data-quality grades. With a commodity code: that series' quality report — overall grade/score plus dimension scores (completeness, freshness, and more) for the current period. Without a code: the API's available catalog summary (grade distribution by category). Use when the user asks how reliable/complete a series is, or which series carry the highest quality grades. The summary works on any valid key; per-commodity access varies. Requires an eligible account entitlement. Use opa_get_plans for current access and pricing; the API response is authoritative.
Inputs: commodity.
opa_get_diesel_by_stateGet Diesel Price by StateARead-onlyInspect
Get the current average retail diesel price for a US state. Use when the user asks about diesel prices in a specific state, diesel fuel costs by state, or state-level fuel prices. Accepts state names ('California') or 2-letter codes ('CA'). Returns the AAA-sourced state average diesel price. Covers all 50 states plus DC.
Inputs: state (required).
opa_get_drillingGet Drilling ActivityARead-onlyInspect
Get a drilling activity snapshot: US, Canada, and international rig counts, frac spread count, well permits issued in the last 30 days (with a by-state breakdown), and DUC (drilled-uncompleted) well totals. Use when the user asks about drilling activity, rigs vs frac spreads, or upstream operations. Requires an eligible account entitlement. Use opa_get_plans for current access and pricing; the API response is authoritative.
Inputs: no named parameters.
opa_get_forecastsGet Price ForecastsARead-onlyInspect
Get energy price forecasts from EIA Short-Term Energy Outlook (STEO) and other sources. Use when the user asks about price predictions, outlooks, or where oil/gas prices are heading. Returns forecast data available to the account. Requires an eligible account entitlement. Use opa_get_plans for current access and pricing; the API response is authoritative.
Inputs: no named parameters.
opa_get_fuel_surchargeGet Fuel SurchargeARead-onlyInspect
Get carrier-published fuel surcharge percentages for LTL freight and parcel carriers. Use when the user asks about current or historical fuel surcharge rates for carriers like ODFL, Saia, Estes, XPO, ABF, TForce, Averitt, Southeastern Freight, UPS, FedEx, or DHL. Auto mode treats UPS/FedEx/DHL as parcel carriers and other carrier slugs as LTL. Parcel history requires a service_level such as ground, air, or international_air_export.
Inputs: mode, carrier, history, per_page, +1 more.
opa_get_futuresGet Futures PriceARead-onlyInspect
Get the latest front-month futures contract price for energy commodities. Use canonical instrument slugs: brent, wti, gasoil, natural-gas, ttf-gas, lng-jkm, eu-carbon, or uk-carbon. Contract codes and older venue slugs remain compatibility inputs. For the forward curve returned for this account, use opa_get_futures_curve instead. Requires an eligible account entitlement. Use opa_get_plans for current access and pricing; the API response is authoritative.
Inputs: contract.
opa_get_futures_curveGet Futures CurveARead-onlyInspect
Get the futures forward-curve contracts returned for this account. Use canonical instrument slugs: brent, wti, gasoil, natural-gas, ttf-gas, lng-jkm, eu-carbon, or uk-carbon. Contract codes and older venue slugs remain compatibility inputs. Returns available contract months with settlement prices plus market-structure analysis. Requires an eligible account entitlement. Use opa_get_plans for current access and pricing; the API response is authoritative.
Inputs: contract.
opa_get_historyGet Price HistoryARead-onlyInspect
Get historical price data for a commodity over a time period. Use when the user asks about price trends, historical prices, or how a commodity has performed over time. Returns high, low, average, change, and data point count. Periods: day (24h), week (7d), month (30d), year (365d). Supports point-in-time filtering via stored observation and revision timestamps. Observation-dated bulk backfills may appear in an earlier as_of result because their actual load time cannot be reconstructed. Requires an eligible account entitlement. Use opa_get_plans for current access and pricing; the API response is authoritative.
Inputs: commodity (required), as_of, period.
opa_get_marine_fuelsGet Marine Fuel PricesARead-onlyInspect
Get latest marine fuel (bunker) prices returned for the account, one row per port and fuel, each with the currency, unit, as-of time, age in days and stale flag the API reports. Use when the user asks about bunker fuel, marine fuel, VLSFO, MGO, IFO380, or shipping fuel costs. Filter by port name or UN/LOCODE (e.g., Singapore or SGSIN, Rotterdam or NLRTM) and/or by the fuel type the API reports: VLSFO, MGO_05S (MGO), HFO_380 (IFO380). Requires an eligible account entitlement. Use opa_get_plans for current access and pricing; the API response is authoritative.
Inputs: port, fuel_type.
opa_get_market_briefMulti-Commodity Market BriefARead-onlyInspect
Get a multi-commodity market brief: latest spot prices, 24h changes, 1-month forecasts (for Brent/WTI/Natural Gas), and notable spreads — for several commodities in ONE call. Use when the user wants a market snapshot, morning brief, or an at-a-glance read across multiple commodities. Set narrative: true to also get a plain-English summary plus market context (active supply disruptions, key economic indicators). Accepts natural language ('brent', 'us gas') or API codes. REQUIRES an API key (OILPRICEAPI_KEY); counts as 1 request. Per-account code limits apply and the API response is authoritative. For a single price use opa_get_price; for ongoing recurring monitoring use opa_create_price_subscription.
Inputs: codes (required), narrative.
opa_get_natural_gas_hubsGet US Natural Gas Hub PricesARead-onlyInspect
Get US physical natural gas hub prices as basis to Henry Hub (USD/MMBtu). Use when the user asks about regional gas prices or hub basis — Waha (West Texas/Permian), SoCal Citygate, Chicago Citygate, Algonquin Citygate, Eastern Gas South (formerly Dominion South), Houston Ship Channel. Without a hub, returns each live hub available to the account plus its basis; with a hub, returns that hub's latest price, basis, and basis history. Hub series differ in depth — check history_days before requesting a long window. Requires an eligible account entitlement. Use opa_get_plans for current access and pricing; the API response is authoritative.
Inputs: hub, past.
opa_get_oil_inventoriesGet EIA Oil InventoriesARead-onlyInspect
Get the latest EIA weekly petroleum inventory (stocks) data. Use when the user asks about oil inventories, crude stocks, weekly EIA stocks, inventory builds/draws, or product-level inventory levels. Returns the latest weekly figures available to the account; optionally a summary view or a breakdown by petroleum product. Requires an eligible account entitlement. Use opa_get_plans for current access and pricing; the API response is authoritative.
Inputs: view.
opa_get_opec_productionGet OPEC ProductionARead-onlyInspect
Get the latest OPEC oil production data. Use when the user asks about OPEC output, production quotas, supply cuts, or OPEC+ compliance. Returns available country-level production figures. Requires an eligible account entitlement. Use opa_get_plans for current access and pricing; the API response is authoritative.
Inputs: no named parameters.
opa_get_plansGet Plans & PricingARead-onlyInspect
Get OilPriceAPI's current subscription plans: monthly/yearly price, request limits, and included features for each tier. Use when the user asks what an upgrade costs, which plan unlocks a gated tool (history, futures, natural gas hubs...), or how the tiers compare. Live pricing from the API — no key required.
Inputs: no named parameters.
opa_get_priceGet Commodity PriceARead-onlyInspect
Get the latest available, source-timestamped value for an energy commodity. Use when the user asks about a single commodity's latest price. Accepts natural language ('brent oil', 'diesel') or API codes ('WTI_USD'). Returns price, currency, available change fields, and timestamp. For multiple commodities at once, use opa_market_overview. For price trends, use opa_get_history.
Inputs: commodity (required).
opa_get_product_factsGet OilPriceAPI Product FactsARead-onlyInspect
Get the reviewed, versioned OilPriceAPI product contract for product scope, evaluation offer, pricing URL, freshness policy, catalog and entitlement wording, authentication, canonical first request, keyless demo, and data-rights boundaries. Use this instead of model memory or package prose for questions about OilPriceAPI itself. No API key or paid-data entitlement is required.
Inputs: no named parameters.
opa_get_rig_countsGet US Rig CountsARead-onlyInspect
Get the latest US rig count (Baker Hughes). Use when the user asks about drilling activity, rig counts, or oil field operations. Returns a single US total rig count with its region and observation date — this source carries no oil/gas split and no prior-week delta. For rigs broken out by US/Canada/international alongside frac spreads and permits, use opa_get_drilling. No parameters needed. Requires an eligible account entitlement. Use opa_get_plans for current access and pricing; the API response is authoritative.
Inputs: no named parameters.
opa_get_spreadGet Refining & Trading SpreadsARead-onlyInspect
Get refining and trading spreads: crack spreads (refining margin proxy), basis spreads (regional price differentials), and blending/transport margins. Use when the user asks about crack spreads, 3-2-1 crack, refining margins, basis differentials, or blend/transport margins. Requires an eligible account entitlement. Use opa_get_plans for current access and pricing; the API response is authoritative.
Inputs: type (required).
opa_get_storageGet Oil Storage LevelsARead-onlyInspect
Get oil storage and inventory levels for Cushing, Oklahoma (WTI delivery hub) and/or the US Strategic Petroleum Reserve (SPR). Use when the user asks about oil inventories, storage levels, Cushing stocks, or the SPR. Returns current inventory levels with changes. Requires an eligible account entitlement. Use opa_get_plans for current access and pricing; the API response is authoritative.
Inputs: facility.
opa_get_subscription_eventsPoll Subscription EventsARead-onlyInspect
Poll for new subscription events — the recurring snapshots recorded by the user's watches. Use this to catch up on what changed since the last poll: pass the since cursor (the seq number) returned by the previous call to get only newer events. Events are POLLED, not pushed — there is no always-on connection, so call this periodically to stay current. Each event carries a price snapshot plus per-code deltas vs the prior snapshot. The returned cursor is what you pass as since next time. REQUIRES an API key (OILPRICEAPI_KEY). This poll does NOT count against the monthly request quota.
Inputs: since.
opa_get_well_activityGet Recent Well ActivityARead-onlyInspect
Get recent US well-permit activity including counts by state, top operators and formations, permit types, and weekly trend. The response also includes every non-available state-health record so stale, degraded, unavailable, or attention states are explicit; rankings must not be treated as complete national coverage when warnings exist. If the state-health index cannot be loaded, the activity summary is still returned, headed as partial, with the reason the health gate is missing.
Inputs: days.
opa_get_well_permitsGet Well PermitsARead-onlyInspect
Get the latest US oil & gas well drilling permit data. Use when the user asks about well permits, new drilling permits, permitting activity, or upstream permit trends. Returns available permits; optionally filtered/aggregated by state or by operator. Requires an eligible account entitlement. Use opa_get_plans for current access and pricing; the API response is authoritative.
Inputs: view, state, operator.
opa_get_well_productionGet Well ProductionARead-onlyInspect
Get US oil & gas well production data (BETA coverage: monthly state-level production from EIA + selected state regulators, and well-level histories for selected states only — NOT complete US well-level production). Views: summary (national + top states), states (reporting states returned by the API, latest month), state (monthly history for one state), well (monthly history for one well by 14-digit API number), top_producers (highest-output wells, optionally by state), cycle_time (permit-to-production cycle time stats, optionally by state), cohorts (cycle times by spud quarter). Use when the user asks about oil/gas production volumes by state or well, top producing wells, or drill-to-production cycle times. Requires an eligible account entitlement. Use opa_get_plans for current access and pricing; the API response is authoritative.
Inputs: view, state, api_number.
opa_list_commoditiesList Available CommoditiesARead-onlyInspect
List the account-visible commodities returned by the live API. Use when the user asks what commodities are available for this account, what codes to use, or when another tool returns a 'commodity not recognized' error. Results are grouped by category. Dataset access varies by account entitlement. No parameters needed.
Inputs: no named parameters.
opa_list_price_alertsList Price AlertsARead-onlyInspect
List all PERSISTENT price alerts on the user's OilPriceAPI account. Use when the user asks what alerts they have set up, or to find an alert's id before deleting it. REQUIRES an API key (OILPRICEAPI_KEY) — alerts are account-scoped. No parameters needed.
Inputs: no named parameters.
opa_list_subscriptionsList Price SubscriptionsARead-onlyInspect
List all PERSISTENT price subscriptions ('watches') on the user's OilPriceAPI account. Use when the user asks what they're monitoring, or to find a watch's id before deleting it. Each watch is a recurring, account-tied snapshot job. REQUIRES an API key (OILPRICEAPI_KEY). No parameters needed.
Inputs: no named parameters.
opa_lookup_wellLook Up Well by API NumberARead-onlyInspect
Look up a well by 10-, 12-, or 14-digit API number using the core API's promoted lifecycle summaries. Returns operator, county, lifecycle dates, cumulative production and evidence; for a 14-digit API number it also includes exact monthly well-production history when available. Optional state disambiguates API numbers that occur across source contexts. Unpromoted or ambiguous records fail closed.
Inputs: api_number (required), state.
opa_market_overviewEnergy Market OverviewARead-onlyInspect
Get the current prices returned by the API for this account in one call. Use when the user wants a broad market snapshot or asks about overall energy prices. Returns available prices grouped by category (oil, gas, coal, refined products, metals, forex) with 24h changes. Supports filtering by category. Dataset access varies by account entitlement. For a single commodity, use opa_get_price instead.
Inputs: category.
opa_search_well_permitsSearch Well PermitsARead-onlyInspect
Search well permits in one US state by county or operator and optional permit-date range. The tool checks the core API's measured state-health gate first, fails closed for unavailable/attention states, and always returns freshness, date coverage, source provenance, and any staleness/degradation caveat with the records. Operator and county filters currently require separate searches.
Inputs: state (required), page, county, end_date, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 32 tools
Most tools target distinct data categories, but clusters like drilling/rigs and price overviews (get_price, market_overview, market_brief, compare_prices) have enough overlap to cause occasional misselection. The detailed descriptions mitigate but do not fully eliminate ambiguity.
All tools share the opa_ prefix and use snake_case with a mostly verb-first pattern (get, list, search, lookup, compare). The noun-phrase opa_market_overview is a minor deviation, but the overall convention is predictable.
At 32 tools, the server is over-instrumented. While the energy domain is broad, many narrow tools (e.g., diesel_by_state, fuel_surcharge, marine_fuels) could be consolidated or parameterized, and the count exceeds the typical practical limit for agent navigation.
Data coverage is extensive, but lifecycle support is incomplete: opa_get_market_brief references opa_create_price_subscription which is not exposed, and there are no create/update/delete tools for subscriptions or alerts. This creates dead ends for persistence workflows.
Maintenance
Related MCP Connectors
Live and historical prices for gold, silver and other metals, energy, currencies and crypto.
Commodity price indices, forward curves and catalog search. Requires a General Index account.
Real-time and historical price feeds for 500+ crypto, equities, FX, and commodities assets.
Primary-source commodities for agents — EIA, USDA, CFTC, IMF, USGS, FAOSTAT, Comtrade. 30 tools.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceExposes energy market signals and readiness indices by integrating data from sources like Yahoo Finance, ENTSOG, and AGSI+. It enables users to query gas flows, storage levels, power prices, and weather data via natural language.-
- AlicenseNot gradedqualityBmaintenanceEnables querying current and historical retail petrol, diesel, and LPG prices across European countries, comparing prices by week, and checking data coverage.85 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables querying monthly oil and gas production, consumption, imports, exports, and closing stocks by country, with tools for time-series lookups, cross-country comparisons, and coverage checks.85 npmMIT
- AlicenseAqualityBmaintenanceEnables users to fetch current and historical prices for 37 US crops from futures, USDA farm, and global benchmark sources, compare commodities, and retrieve group snapshots.5MIT