oilpriceapi-mcp on npm · MCP RegistryOil Price MCP Server by OilPriceAPI for AI Agents
The OilPriceAPI MCP server (oilpriceapi-mcp) lets Claude, Cursor and other MCP clients fetch source-timestamped oil, gas and commodity prices from OilPriceAPI on their own.
Quick start
- Check the package runs:
npx oilpriceapi-mcp doctor --demo - Paste the config for your client below. Replace
your-api-key-herewith your key, or delete theenvblock to run in keyless demo mode. - Restart the client and ask: "What's the current Brent oil price?"
Hosted remote server, nothing to install
Clients that support remote MCP servers can connect to https://mcp.oilpriceapi.com/mcp (Streamable HTTP). In Claude, add it as a custom connector. Latest prices for the demo set answer without an account; for other datasets the client asks you to connect your OilPriceAPI account, with read-only access.
The hosted server carries the core price, history, futures, marine fuel, drilling and catalog tools. Alerts, watches and the other account tools are in the npm package below.
Claude Desktop
Config file: ~/Library/Application Support/Claude/claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json)
{
"mcpServers": {
"oilpriceapi": {
"command": "npx",
"args": ["-y", "oilpriceapi-mcp"],
"env": {
"OILPRICEAPI_KEY": "your-api-key-here"
}
}
}
}Claude Code
Config file: .mcp.json (project root)
{
"mcpServers": {
"oilpriceapi": {
"command": "npx",
"args": ["-y", "oilpriceapi-mcp"],
"env": {
"OILPRICEAPI_KEY": "your-api-key-here"
}
}
}
}Cursor
Config file: .cursor/mcp.json (project root)
{
"mcpServers": {
"oilpriceapi": {
"command": "npx",
"args": ["-y", "oilpriceapi-mcp"],
"env": {
"OILPRICEAPI_KEY": "your-api-key-here"
}
}
}
}VS Code + Cline
Config file: .vscode/mcp.json
{
"servers": {
"oilpriceapi": {
"type": "stdio",
"command": "npx",
"args": ["-y", "oilpriceapi-mcp"],
"env": {
"OILPRICEAPI_KEY": "your-api-key-here"
}
}
}
}Windsurf
Config file: ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"oilpriceapi": {
"command": "npx",
"args": ["-y", "oilpriceapi-mcp"],
"env": {
"OILPRICEAPI_KEY": "your-api-key-here"
}
}
}
}npx oilpriceapi-mcp --config <client> prints the same config for claude-desktop, claude-code, cursor, vscode, cline or windsurf without reading or printing your key. A step-by-step walkthrough is in the MCP server tutorial.
Live example
Ask in plain language. The assistant picks opa_get_price, which reads the same latest record shown here.
Ask your assistant
What's the current Brent oil price?Latest BRENT_CRUDE_USD from the API
$95.55per barrel
As of 2026-11-15 23:26 UTC
The tool answer includes the price, unit and timestamp, so the assistant can say how current the value is.
Tools
Every tool is prefixed with opa_ so it does not collide with other MCP servers. Run npx oilpriceapi-mcp --list-tools for the exact inventory of the version you installed.
Prices, history and futures
Price tools work in keyless demo mode for the demo set
opa_get_product_facts | Reviewed product, offer, freshness, auth and entitlement facts (keyless) |
opa_get_price | Current spot price for a single commodity |
opa_market_overview | Account-visible current prices, grouped by category |
opa_compare_prices | Side-by-side comparison of 2-5 commodities with spread |
opa_list_commodities | Account-visible commodity catalog from the live API |
opa_get_history | Historical prices with high/low/avg/change (day/week/month/year) |
opa_get_futures | Front-month futures (Brent, WTI, gasoil, TTF, JKM, EU carbon) |
opa_get_futures_curve | Forward curve with contango/backwardation analysis |
opa_get_spread | Refining and trading spreads (crack, basis, margin) |
Fuel, supply and drilling data
API key; access depends on account entitlement
opa_get_marine_fuels | Bunker fuel prices by port and grade (VLSFO/MGO/IFO380) |
opa_get_diesel_by_state | AAA retail diesel price for any US state (50 states + DC) |
opa_get_fuel_surcharge | LTL and parcel carrier fuel surcharge percentages with effective dates |
opa_get_storage | Cushing and SPR oil storage and inventory levels |
opa_get_oil_inventories | EIA weekly petroleum stocks |
opa_get_opec_production | OPEC country-level production data |
opa_get_forecasts | EIA STEO energy price forecasts |
opa_get_rig_counts | Baker Hughes US rig count with region and observation date |
opa_get_drilling | Rig counts, frac spreads, 30-day permits and DUCs |
opa_get_well_permits | US well permits (latest, by state, by operator) |
opa_search_well_permits | State-scoped permit search by county, operator or date |
opa_lookup_well | API-number lookup with lifecycle and monthly production |
opa_get_well_activity | Recent permit counts, top operators and trends |
opa_get_well_production | US well production (beta coverage) |
Briefs, alerts and watches
API key; create/delete tools also need --scope write
opa_get_market_brief | Multi-commodity brief: prices, 24h changes and spreads |
opa_create_price_alert | Create a persistent price alert (write scope) |
opa_list_price_alerts | List the alerts on the account |
opa_delete_price_alert | Delete an alert by id (write scope) |
opa_get_alert_triggers | Recent alert trigger activity |
opa_create_price_subscription | Create a recurring price watch (write scope) |
opa_list_subscriptions | List the watches on the account |
opa_delete_subscription | Delete a watch by id (write scope) |
opa_get_subscription_events | Poll for new watch events since a cursor |
Frequently asked questions
What is an oil price MCP server?
MCP (Model Context Protocol) is an open standard that lets AI assistants call external tools. The OilPriceAPI MCP server exposes oil, gas and commodity price tools, so Claude, Cursor or another MCP client can fetch a current, source-timestamped price itself instead of you pasting one into the chat.
Is the MCP server free?
The server is open source under the MIT license and free to install. Keyless demo mode works without an account. A free API key includes 50 requests per day, and paid plans add higher limits and more datasets.
Do I need an API key?
Not to try it. Leave OILPRICEAPI_KEY out of the config and the price tools answer from the keyless demo for a limited commodity set; other tools explain what they need. Add a free API key for the broader catalog, history, futures and alerts your account is entitled to.
Which MCP clients does it work with?
Two ways. Any client that supports remote MCP servers, including Claude as a custom connector, can use the hosted server at https://mcp.oilpriceapi.com/mcp with nothing to install. The npm package runs locally through npx in Claude Desktop, Claude Code, Cursor, VS Code with Cline, Windsurf and any other stdio MCP client. Run npx oilpriceapi-mcp --config claude-code (or cursor, vscode, cline, windsurf, claude-desktop) to print a ready-to-paste config.
Can the assistant change anything on my account?
Not by default. Since version 3.0.0 the server starts in read-only scope: the tools that create or delete alerts and watches are hidden and rejected unless you start it with --scope write or set OILPRICEAPI_MCP_SCOPE=write.
Is it listed in the official MCP Registry?
Yes. The registry name is io.github.OilpriceAPI/mcp-server, published from the npm package oilpriceapi-mcp. The source is on GitHub at github.com/OilpriceAPI/mcp-server.
What does the server send to OilPriceAPI?
Only the structured tool inputs, such as commodity codes, a time period or a US state, sent over HTTPS to api.oilpriceapi.com with your key. Conversation content is not transmitted.
Registry record: io.github.OilpriceAPI/mcp-server · npm: oilpriceapi-mcp · source: github.com/OilpriceAPI/mcp-server
Give your agent source-timestamped oil prices
Start in demo mode, then add a free key for the catalog your account is entitled to.