OilPriceAPI — Real-Time Oil, Gas & Commodity Prices for AI Agents

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 byOilPriceAPI, 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

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

The server works out of the box inkeyless demo mode— just omitOILPRICEAPI_KEYfrom 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 keyand add it to your config.

{ "mcpServers": { "oilpriceapi": { "command": "npx", "args": ["-y", "oilpriceapi-mcp"], "env": { "OILPRICEAPI_KEY": "your-api-key-here" } } } }

{ "mcpServers": { "oilpriceapi": { "command": "npx", "args": ["-y", "oilpriceapi-mcp"], "env": { "OILPRICEAPI_KEY": "your-api-key-here" } } } }

Add to.cursor/mcp.jsonin your project root:

{ "mcpServers": { "oilpriceapi": { "command": "npx", "args": ["-y", "oilpriceapi-mcp"], "env": { "OILPRICEAPI_KEY": "your-api-key-here" } } } }

{ "servers": { "oilpriceapi": { "type": "stdio", "command": "npx", "args": ["-y", "oilpriceapi-mcp"], "env": { "OILPRICEAPI_KEY": "your-api-key-here" } } } }

Add to~/.codeium/windsurf/mcp_config.json:

{ "mcpServers": { "oilpriceapi": { "command": "npx", "args": ["-y", "oilpriceapi-mcp"], "env": { "OILPRICEAPI_KEY": "your-api-key-here" } } } }

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

The runtime image uses the unprivilegednodeuser. OmitOILPRICEAPI_KEYfor the limited keyless demo, or inject it with your container platform's secret manager. Do not bake credentials into the image.

readscope includes all non-mutating tools, including alert history, subscription listing, and subscription event polling. The four create/delete tools require--scope writeorOILPRICEAPI_MCP_SCOPE=write. Unknown scope, profile, or category values fail closed before stdio starts.

Profiles reduce tool overload without replacing first-class MCP actions:

For example, a read-only price and product-facts server can use:

{ "command": "npx", "args": ["-y", "oilpriceapi-mcp", "--scope", "read", "--profile", "core"] }

doctorchecks the Node runtime, package entry point, API reachability, key validity, current plan, and reported feature gates.doctor --demoperforms 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 includesbuild/capabilities.json. It is generated from the same SDK registry used bytools/listand 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, validateschemaVersionandsourceCommit, and update the artifact only through an explicit dependency upgrade. They should not scrape CLI prose or hard-code tool counts.

All tools are prefixed withopa_to avoid name collisions when multiple MCP servers are loaded.

These tools create and managepersistentprice alerts tied to your OilPriceAPI account, so theyrequire 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.

Market Brief & Subscription Tools (authenticated)

The market brief gives a multi-commodity snapshot in one call. Subscriptions ("watches") arepersistent, recurringsnapshots tied to your account — the API records an event every interval, and the agentpollsfor new events via a per-user cursor (events are polled, not pushed — there is no always-on connection). Theserequire 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.

"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?" "What's the UPS ground fuel surcharge?" "Show me the gasoil futures curve"

opa_get_product_factsandoilpriceapi://product-factsimprove 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.

npm install npm run build npm test OILPRICEAPI_KEY=your-key node build/index.js

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

- All tool names now useopa_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)

- 🧭Interactive explorer:api.oilpriceapi.com/swagger— try every endpoint in the browser (demo mode, no key needed)
- 📜OpenAPI spec:swagger.json

- What is sent: tool requests are translated into HTTPS calls toapi.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 theOILPRICEAPI_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 toprovided. API request logging follows theOilPriceAPI 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.

- Always open: the MCP server itself (MIT), setup, docs, discovery (tool listing), and keyless demo mode for low-volume evaluation.
- API key: use thepublic product factsand 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 standardHTTP 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 thex402 protocolarenot currently supported— payment is by account plan (Stripe), authenticated with your API key.

- OilPriceAPI
- API Documentation
- Pricing
- MCP Protocol

- Python SDK- Python client with Pandas integration
- Node.js SDK- TypeScript/JavaScript SDK
- Go SDK- Idiomatic Go client
- OpenBB Integration- OpenBB Platform provider

A simple MCP server that grabs prediction market data from polymarket, PredictIt, & Kalshi.