OilpriceAPI/mcp-server

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 …

Get dated price rows for up to 5 commodities between a start date and an optional end date (YYYY-MM-DD, UTC), aggregated hourly, daily, weekly or monthly. Use when the user needs the actual series (e.g. daily Brent and heating oil from 2025-01-01 to 2025-06-30) rather than summary statistics over a fixed window, which opa_get_history returns. Results are paged at up to 500 rows per page across all requested codes, newest rows first: page 1 holds the most recent dates and later pages go back in time; within a page each code's rows are listed oldest to newest. The answer states the page count an…

Get the daily price history of one marine fuel at one port: one row per assessment date with price, currency, unit and collection time, plus high/low over the rows returned. Use when the user asks how bunker prices at a port moved over days or months. Needs the port's UN/LOCODE (resolve names with opa_get_marine_ports) and a fuel type: VLSFO, MGO_05S (MGO), HFO_380 (IFO380) or HFO_180. Requires a paid subscription or an active trial; other accounts get HTTP 403. The API rate-limits history more tightly than latest prices and caps the rows per request, so a long window can come back shorter tha…

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.

List the bunkering ports the API carries (UN/LOCODE, name, country, region, major-port flag, fuel services, trading hours), or read one port with its prices collected in the last 24 hours. Use it to resolve a port name to the UN/LOCODE that opa_get_marine_fuel_history needs, or to check which fuel services a port lists. Works with any valid API key; the API applies its own marine per-minute rate limit. Requires an eligible account entitlement. Use opa_get_plans for current access and pricing; the API response is authoritative.

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 authoritat…

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 p…

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.

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.

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.

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.

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.

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.

Get refining and trading spreads: crack spreads (refining margin proxy), basis spreads (regional price differentials), and refinery margins, latest or as a daily history. Use when the user asks about crack spreads, 3-2-1 crack, refining margins, Brent-WTI, Waha or JKM/TTF vs Henry Hub basis. crack: crack_type 3-2-1|jet|diesel|gasoline (default 3-2-1) against crude BRENT_CRUDE_USD|WTI_USD|BRENT_SPOT_USD|WTI_SPOT_USD (default BRENT_CRUDE_USD). basis: pair WAHA_HH|BRENT_WTI|BRENT_DUBAI|JKM_HH|TTF_HH|BRENT_OMAN; omit pair to list every pair (/basis/all). margin: index usgc|singapore|nwe (default u…

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.

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.

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.

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.

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 u…

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.

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.

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.

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.

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.

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.