Mcp Server

OilPriceAPI MCP Server

The energy commodity MCP server. Real-time oil, gas, and commodity prices for Claude, Cursor, VS Code, and any MCP-compatible client.

Features

• 21 Tools — 17 read tools (spot prices, history, futures, marine fuels, rig counts, diesel by state, storage, OPEC production, forecasts, EIA oil inventories, well permits, refining spreads) plus 4 authenticated price-alert tools (create/list/delete persistent alerts + trigger activity)
• 5 Resources — subscribable price snapshots for Brent, WTI, Natural Gas, Diesel, and all commodities
• 6 Prompts — pre-built analyst templates (daily briefing, spread analysis, gas markets, commodity report, diesel costs, supply analysis)
• Natural language — ask for "brent oil" or "natural gas", not codes
• 70+ commodities — oil, gas, coal, refined products, metals, forex, bunker fuels, state diesel
• Smart errors — unrecognized commodities get suggestions, not silent fallbacks

Quick Start

npx oilpriceapi-mcp

Installation

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-mcp

Environment Variables

Variable	Required	Description
OILPRICEAPI_KEY	Yes	API key from oilpriceapi.com/signup. Free tier: 200 requests/month.
OILPRICEAPI_BASE_URL	No	Override API base URL (for staging/testing). Default: https://api.oilpriceapi.com

Tools

All tools are prefixed with opa_ to avoid name collisions when multiple MCP servers are loaded.

Tool	Description
opa_get_price	Current spot price for a single commodity
opa_market_overview	All commodity prices in one call, grouped by category
opa_compare_prices	Side-by-side comparison of 2-5 commodities with spread
opa_list_commodities	Full commodity catalog (fetched live from API)
opa_get_history	Historical prices with high/low/avg/change (day/week/month/year)
opa_get_futures	Front-month futures (Brent BZ, WTI CL, ICE Gasoil, TTF, JKM, EUA)
opa_get_futures_curve	Full forward curve with contango/backwardation analysis
opa_get_marine_fuels	Bunker fuel prices by port and fuel type (VLSFO/MGO/IFO380)
opa_get_rig_counts	Baker Hughes US rig count with week-over-week change
opa_get_drilling	Drilling intelligence: wells, permits, completions by region
opa_get_diesel_by_state	AAA retail diesel price for any US state (50 states + DC)
opa_get_storage	Cushing and SPR oil storage/inventory levels
opa_get_opec_production	OPEC country-level production data
opa_get_forecasts	EIA STEO energy price forecasts
opa_get_oil_inventories	EIA weekly petroleum stocks (latest/summary/by_product)
opa_get_well_permits	US well drilling permits (latest/by_state/by_operator)
opa_get_spread	Refining/trading spreads (crack, basis, margin)

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 continuously watches live prices and notifies you (by email, plus webhook if you provide one) when a condition is met.

Tool	Description
opa_create_price_alert	Create a persistent alert (commodity, operator, threshold, optional webhook)
opa_list_price_alerts	List all alerts on the account
opa_delete_price_alert	Permanently delete an alert by id
opa_get_alert_triggers	Recent alert trigger activity (optionally filtered by since)

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-tier limits apply (free: 1 watch, 3 codes, 1h minimum interval); the API returns the exact limit if exceeded.

Tool	Description
opa_get_market_brief	Multi-commodity brief: prices, 24h changes, 1m forecasts, spreads, optional narrative
opa_create_price_subscription	Create a persistent recurring watch (codes, interval like 5m/1h/daily)
opa_list_subscriptions	List all subscriptions on the account
opa_delete_subscription	Permanently delete a subscription by id
opa_get_subscription_events	Poll for new watch events since a cursor (since); returns snapshots + deltas

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 oil 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?"
"Show me the ICE Gasoil futures curve"

Resources

Subscribable price data (JSON):

Resource	URI	Description
Brent Crude	price://brent	Global benchmark crude oil price
WTI Crude	price://wti	US benchmark crude oil price
Natural Gas	price://natural-gas	US Henry Hub natural gas price
Diesel	price://diesel	US national average diesel price
All Prices	price://all	All tracked commodity prices

Prompts

Pre-built analyst templates:

Prompt	Description
daily-briefing	Energy market daily briefing with key prices and movers
brent-wti-spread	Analyze the Brent-WTI crude oil spread
gas-market-analysis	Compare US vs European natural gas markets
commodity-report	Detailed report on a specific commodity (parameterized)
diesel-cost-analysis	Compare diesel prices across US states for fleet planning
supply-analysis	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.js

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_commodities now fetches live from the API (falls back to static list if unavailable)

License

MIT

Links

• OilPriceAPI
• API Documentation
• Pricing
• MCP Protocol

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