# io.github.OilpriceAPI/mcp-server (npm · oilpriceapi-mcp)

Source-timestamped energy data and reviewed OilPriceAPI product facts for MCP clients.

- Trust score: 81/100 (high trust)
- Change this week: +29
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- npm · `oilpriceapi-mcp`: 81/100 (this document), [markdown](https://verifymcp.io/servers/oilpriceapi-mcp-server/oilpriceapi-mcp.md), [page](https://verifymcp.io/servers/oilpriceapi-mcp-server/oilpriceapi-mcp)

## Channel facts

- Registry: `npm`
- Package: `oilpriceapi-mcp`
- Version: `3.0.0`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Supply Chain Security**: 87/100
  - No malware found by supply-chain analysis.
  - Only part of the dependency tree could be resolved (95 of 99), so this covers what we could see, not the whole tree.
  - No install/post-install scripts declared.
  - Only part of the dependency tree could be resolved (95 of 99), so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 97/100
  - Source repository is publicly reachable at the declared URL.
  - Cryptographically verified build provenance (signed, bound to OilpriceAPI/mcp-server).
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 14 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 83/100
  - 100% of prompts and resources have a non-trivial description (not blank, and not just the item's name).
  - AI-judged instruction clarity (excellent).
  - Context-footprint check failed: tool/resource definitions use about 3634 tokens (~117/item across 31 items; 25 tools + 6 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 27/100
  - Stability observed for 8 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add oilpriceapi-mcp-server -- npx -y oilpriceapi-mcp
```

### Codex

```bash
codex mcp add oilpriceapi-mcp-server -- npx -y oilpriceapi-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "oilpriceapi-mcp-server": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "oilpriceapi-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add oilpriceapi-mcp-server --command npx --arg -y --arg oilpriceapi-mcp
```

### Hermes

```yaml
mcp_servers:
  oilpriceapi-mcp-server:
    command: "npx"
    args: ["-y", "oilpriceapi-mcp"]
```

### Other

```json
{
  "mcpServers": {
    "oilpriceapi-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "oilpriceapi-mcp"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-02 (score 81, +55)

- [security improvement] Install scripts: unverified → pass
- [security improvement] Provenance: unverified → pass
- [security improvement] Known CVEs: unverified → partial
- [security improvement] Malware scan: unverified → pass
- [security] The attested source repository moved: OilpriceAPI/mcp-server
- [functional improvement] Schema quality: unverified → excellent
- [functional improvement] License: unverified → pass
- [functional improvement] Dependency health: unverified → partial
- [functional improvement] Maintenance: unverified → pass
- [functional improvement] MCP protocol: unverified → pass
- [functional improvement] Stability: unverified → 0.23
- [functional] Licence: MIT

### 2026-07-31 (score 26, −26)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-30 (score 52, +28)

- [functional improvement] Tool coverage: unverified → 100
- [functional improvement] Schema quality: unverified → 100

### 2026-07-28 (score 24, −28)

- [functional regression] Tool coverage: 100 → unverified
- [functional regression] Schema quality: 100 → unverified

### 2026-07-27 (score 52)

First indexed and scored.

## MCP tools (25)

### `opa_get_product_facts` (~83 tokens)

Get OilPriceAPI Product Facts

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.

### `opa_get_price` (~125 tokens)

Get Commodity Price

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.

Input parameters:

- `commodity` (string, required): Commodity name or code (e.g., 'brent oil', 'natural gas', 'WTI_USD', 'diesel')

### `opa_market_overview` (~108 tokens)

Energy Market Overview

Get current prices for all tracked energy commodities in one call. Use when the user wants a broad market snapshot or asks about overall energy prices. Returns prices grouped by category (oil, gas, coal, refined products, metals, forex) with 24h changes. Supports filtering by category. For a single commodity, use opa_get_price instead.

Input parameters:

- `category` (string): Filter by commodity category (default: all). Options: oil, gas, coal, refined, metals, forex.

### `opa_compare_prices` (~126 tokens)

Compare Commodity Prices

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.

Input parameters:

- `commodities` (array, required): List of 2-5 commodity names or codes to compare (e.g., ['brent', 'wti'] or ['NATURAL_GAS_USD', 'DUTCH_TTF_EUR'])

### `opa_list_commodities` (~68 tokens)

List Available Commodities

List all available commodities that can be queried for prices. Use when the user asks what commodities are available, what codes to use, or when another tool returns a 'commodity not recognized' error. Returns the full catalog fetched live from the API, grouped by category. No parameters needed.

### `opa_get_history` (~125 tokens)

Get Price History

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).

Input parameters:

- `commodity` (string, required): Commodity name or code (e.g., 'brent', 'WTI_USD')
- `period` (string): Time period: day, week, month, or year (default: month)

### `opa_get_futures` (~239 tokens)

Get Futures Price

Get the latest front-month futures contract price for energy commodities. Use when the user asks about futures, forward prices, or contract prices. Supports crude oil (BZ/ice-brent = Brent, CL/ice-wti = WTI), ICE Gasoil (ice-gasoil), natural gas (natural-gas), European TTF gas (ttf-gas), LNG JKM (lng-jkm), EUA carbon (eua-carbon), and UK carbon (uk-carbon). For the full forward curve across all contract months, use opa_get_futures_curve instead.

Input parameters:

- `contract` (string): Futures contract code or slug: BZ/ice-brent = Brent crude, CL/ice-wti = WTI crude, ice-gasoil (G/QS) = ICE Gasoil, natural-gas (NG) = Natural Gas, ttf-gas (TTF) = European TTF natural gas, lng-jkm (J…

### `opa_get_futures_curve` (~243 tokens)

Get Futures Curve

Get the full futures forward curve showing prices across all contract months. Use when the user asks about the forward curve, contango/backwardation, or term structure. Supports crude oil (BZ/ice-brent = Brent, CL/ice-wti = WTI), ICE Gasoil (ice-gasoil), natural gas (natural-gas), European TTF gas (ttf-gas), LNG JKM (lng-jkm), EUA carbon (eua-carbon), and UK carbon (uk-carbon). Returns a table of contract months with settlement prices, plus market structure analysis.

Input parameters:

- `contract` (string): Futures contract code or slug: BZ/ice-brent = Brent crude, CL/ice-wti = WTI crude, ice-gasoil (G/QS) = ICE Gasoil, natural-gas (NG) = Natural Gas, ttf-gas (TTF) = European TTF natural gas, lng-jkm (J…

### `opa_get_marine_fuels` (~152 tokens)

Get Marine Fuel Prices

Get latest marine fuel (bunker) prices across major shipping ports. 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 a table of port prices.

Input parameters:

- `fuel_type` (string): Filter by fuel type: VLSFO, MGO, or IFO380
- `port` (string): Filter by port name (e.g., 'SINGAPORE', 'ROTTERDAM', 'HOUSTON')

### `opa_get_rig_counts` (~63 tokens)

Get US Rig Counts

Get 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.

### `opa_get_drilling` (~84 tokens)

Get Drilling Activity

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 a paid plan with energy intelligence access.

### `opa_get_diesel_by_state` (~112 tokens)

Get Diesel Price by State

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.

Input parameters:

- `state` (string, required): US state name or 2-letter code (e.g., 'California', 'CA', 'Texas', 'TX')

### `opa_get_fuel_surcharge` (~289 tokens)

Get Fuel Surcharge

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.

Input parameters:

- `carrier` (string): Optional carrier slug or common name. Examples: odfl, saia, estes, xpo, abf, tforce, averitt, southeastern-freight, ups, fedex, dhl. Omit to list current carriers.
- `history` (boolean): When true, return historical surcharge rows instead of the latest rate. Parcel history requires service_level.
- `mode` (string): Carrier mode: auto (UPS/FedEx/DHL route to parcel; others route to LTL), ltl, or parcel. Default: auto.
- `per_page` (integer): History rows to return, from 1 to 100. Default: 12.
- `service_level` (string): Parcel service level such as ground, air, international_air_export, international_air_import, or international_ground. Optional for latest; required for parcel history.

### `opa_get_storage` (~94 tokens)

Get Oil Storage Levels

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.

Input parameters:

- `facility` (string): Storage facility: cushing (WTI delivery hub), spr (Strategic Petroleum Reserve), or all (default: all)

### `opa_get_opec_production` (~58 tokens)

Get OPEC Production

Get the latest OPEC oil production data. Use when the user asks about OPEC output, production quotas, supply cuts, or OPEC+ compliance. Returns country-level production figures. Requires a paid plan with energy intelligence access.

### `opa_get_forecasts` (~66 tokens)

Get Price Forecasts

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 for key commodities. Requires a paid plan with energy intelligence access.

### `opa_get_oil_inventories` (~123 tokens)

Get EIA Oil Inventories

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; optionally a summary view or a breakdown by petroleum product. Requires a paid plan with energy intelligence access.

Input parameters:

- `view` (string): Which view to return: latest (most recent weekly snapshot), summary (headline totals + week-over-week change), or by_product (breakdown per petroleum product). Default: latest.

### `opa_get_well_permits` (~145 tokens)

Get Well Permits

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 the latest permits; optionally filtered/aggregated by state or by operator. Requires a paid plan with energy intelligence access.

Input parameters:

- `state` (string): Optional US state name or 2-letter code to filter permits (e.g., 'Texas', 'TX'). Applies to the latest and by_state views.
- `view` (string): Which view to return: latest (most recent permits), by_state (counts aggregated per state), or by_operator (counts aggregated per operator). Default: latest.

### `opa_get_well_production` (~296 tokens)

Get Well Production

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 (all reporting states, 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 a paid plan with energy intelligence access.

Input parameters:

- `api_number` (string): 14-digit API well number (e.g., '42329447130000'). Required for the well view.
- `state` (string): US state name or 2-letter code (e.g., 'Texas', 'TX'). Required for the state view; optional filter for top_producers and cycle_time.
- `view` (string): Which view to return: summary (national + top states), states (all reporting states), state (one state's monthly history — requires 'state'), well (one well's monthly history — requires 'api_number')…

### `opa_get_spread` (~120 tokens)

Get Refining & Trading Spreads

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 a paid plan with energy intelligence access.

Input parameters:

- `type` (string, required): Spread type: crack (refining crack spread, e.g. 3-2-1), basis (regional/grade price differential), or margin (blending/transport margin).

### `opa_list_price_alerts` (~73 tokens)

List Price Alerts

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.

### `opa_get_alert_triggers` (~154 tokens)

Get Alert Triggers

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.

Input parameters:

- `since` (string): Optional ISO 8601 date/time (e.g., '2026-06-01' or '2026-06-01T00:00:00Z'). Only alerts last triggered on or after this time are shown.

### `opa_get_market_brief` (~253 tokens)

Multi-Commodity Market Brief

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-tier code limits apply (free: 3 codes). For a single price use opa_get_price; for ongoing recurring monitoring use opa_create_price_subscription.

Input parameters:

- `codes` (array, required): Commodity names or codes to include (e.g., ['brent', 'wti'] or ['BRENT_CRUDE_USD', 'NATURAL_GAS_USD']). Free tier allows up to 3.
- `narrative` (boolean): If true, also include a plain-English summary + market context (disruptions, indicators). Default: false (structured data only).

### `opa_list_subscriptions` (~78 tokens)

List Price Subscriptions

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.

### `opa_get_subscription_events` (~181 tokens)

Poll Subscription Events

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.

Input parameters:

- `since` (integer): Cursor: only return events with a seq greater than this. Use the `cursor` from the previous call. Omit (or 0) to get the earliest available events.

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/oilpriceapi-mcp-server/oilpriceapi-mcp#diagnostics

## Score history

- 2026-08-03: 81
- 2026-08-02: 81
- 2026-08-01: 26
- 2026-07-31: 26
- 2026-07-30: 52
- 2026-07-28: 24
- 2026-07-27: 52

## Links

- npm package: https://www.npmjs.com/package/oilpriceapi-mcp
- Socket report: https://socket.dev/npm/package/oilpriceapi-mcp
- Repository: https://github.com/OilpriceAPI/mcp-server
- Changelog RSS feed: https://verifymcp.io/servers/oilpriceapi-mcp-server/oilpriceapi-mcp/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/oilpriceapi-mcp-server/oilpriceapi-mcp/changelog.json
- HTML version of this page: https://verifymcp.io/servers/oilpriceapi-mcp-server/oilpriceapi-mcp