MCP SERVER · OFFICIAL PROJECTGet a source-timestamped energy price by name or code, then go past spot into forward curves, US gas hub basis, bunker fuels, rig counts, EIA inventories, well permits and crack spreads.
LABSCO SUMMARY
The gated tools name their own entitlement and point at the plans call, and the account-status call is explicitly the one to make after a refusal so the answer is what your plan covers rather than a status code. The data tools are equally plain about coverage: well production is marked beta and says outright that it is not complete US well-level data, the permit search fails closed on a state whose health check is failing rather than quietly returning partial results, and the activity view returns every unavailable state so a ranking cannot be mistaken for national coverage.
An energy market data client over OilPriceAPI — spot prices and history, futures and forward curves, physical gas hubs, marine fuels, US upstream activity, inventories, spreads, forecasts, and account-scoped alerts and watches. It runs from npx and works with no key at all in demo mode; the tool surface defaults to read-only, and mutations are refused unless you turn write scope on.
Nothing to start: without a key it runs in demo mode, where the price, comparison, catalog and overview tools serve a limited commodity set and every other tool explains what its account would need. A free key widens the catalog and unlocks history, futures and alerts, and the gated datasets — gas hubs, marine fuels, rig counts, drilling, storage, OPEC production, forecasts, inventories, spreads — each need an eligible plan, which opa_get_plans and opa_get_account_status will tell you about. The default scope is read-only; account mutations are refused until write scope is enabled explicitly.
One command — npx oilpriceapi-mcp
USE CASES
Ask in plain language; an unrecognised name comes back with suggestions rather than a silent fallback, and the catalog call lists what this account can see.
Run it with no key at all: the price, comparison and overview tools answer for a limited demo set, and the responses say so.
One call for spot prices, changes, near-term forecasts and notable spreads, instead of a dozen lookups stitched together.
Read the front-month contract, then the curve behind it, to see whether the market is in contango or backwardation.
Hub basis for regional gas, bunker prices at the port you actually lift at, and the state diesel average behind a fuel surcharge.
Rig counts and frac spreads, permits by state and operator, and the inventories those barrels end up in.
Read the plan, usage and remaining quota, then the current tiers and what each unlocks — the refusal names the entitlement it wanted.
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
opa_compare_pricesCompare 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.
opa_get_account_statusGet 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.
opa_get_alert_triggersGet 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.
opa_get_data_qualityGet 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.
opa_get_diesel_by_stateGet 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.
opa_get_drillingGet 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.
opa_get_forecastsGet 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.
opa_get_fuel_surchargeGet 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.
opa_get_futuresGet 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.
opa_get_futures_curveGet 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.
opa_get_historyGet 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.
opa_get_marine_fuelsGet latest marine fuel (bunker) prices returned for the account. Use when the user asks about bunker fuel, marine fuel, VLSFO, MGO, IFO380, or shipping fuel costs. Can filter by port (e.g., SINGAPORE, ROTTERDAM, HOUSTON) and/or fuel type (VLSFO, MGO, IFO380). Returns available port prices. Requires an eligible account entitlement. Use opa_get_plans for current access and pricing; the API response is authoritative.
opa_get_market_briefGet 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.
opa_get_natural_gas_hubsGet 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.
opa_get_oil_inventoriesGet 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.
opa_get_opec_productionGet 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.
opa_get_plansGet 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.
opa_get_priceGet 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.
opa_get_product_factsGet 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.
opa_get_rig_countsGet the latest US oil and gas rig count data (Baker Hughes). Use when the user asks about drilling activity, rig counts, or oil field operations. Returns oil rigs, gas rigs, total count, and week-over-week change. No parameters needed. Requires an eligible account entitlement. Use opa_get_plans for current access and pricing; the API response is authoritative.
opa_get_spreadGet 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.
opa_get_storageGet 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.
opa_get_subscription_eventsPoll 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.
opa_get_well_activityGet 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.
opa_get_well_permitsGet 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.
opa_get_well_productionGet 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.
opa_list_commoditiesList 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.
opa_list_price_alertsList 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.
opa_list_subscriptionsList 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.
opa_lookup_wellLook 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.
opa_market_overviewGet 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.
opa_search_well_permitsSearch 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.
BEFORE YOU INSTALL
32 tools when we connected; the project documents 36. The four create and delete tools for price alerts and subscriptions need --scope write or OILPRICEAPI_MCP_SCOPE=write; the default scope is read-only. --profile core cuts the set further.
npx on PATH
OILPRICEAPI_KEY in your environment
All 6 documented clients run the server on your machine.
INSTALLATION
npx oilpriceapi-mcp{
"mcpServers": {
"oilpriceapi": {
"command": "npx",
"args": [
"-y",
"oilpriceapi-mcp"
],
"env": {
"OILPRICEAPI_KEY": "<YOUR_OILPRICEAPI_KEY>"
}
}
}
}{
"servers": {
"oilpriceapi": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"oilpriceapi-mcp"
],
"env": {
"OILPRICEAPI_KEY": "<YOUR_OILPRICEAPI_KEY>"
}
}
}
}{
"mcpServers": {
"oilpriceapi": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"oilpriceapi-mcp"
],
"env": {
"OILPRICEAPI_KEY": "<YOUR_OILPRICEAPI_KEY>"
}
}
}
}MCP servers
jcaple
ferdousbhai
azmartone67
zemloai-ctrl