Open source · oilpriceapi-mcp on npm · MCP Registry

Oil 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

  1. Check the package runs: npx oilpriceapi-mcp doctor --demo
  2. Paste the config for your client below. Replace your-api-key-here with your key, or delete the env block to run in keyless demo mode.
  3. 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_factsReviewed product, offer, freshness, auth and entitlement facts (keyless)
opa_get_priceCurrent spot price for a single commodity
opa_market_overviewAccount-visible current prices, grouped by category
opa_compare_pricesSide-by-side comparison of 2-5 commodities with spread
opa_list_commoditiesAccount-visible commodity catalog from the live API
opa_get_historyHistorical prices with high/low/avg/change (day/week/month/year)
opa_get_futuresFront-month futures (Brent, WTI, gasoil, TTF, JKM, EU carbon)
opa_get_futures_curveForward curve with contango/backwardation analysis
opa_get_spreadRefining and trading spreads (crack, basis, margin)

Fuel, supply and drilling data

API key; access depends on account entitlement

opa_get_marine_fuelsBunker fuel prices by port and grade (VLSFO/MGO/IFO380)
opa_get_diesel_by_stateAAA retail diesel price for any US state (50 states + DC)
opa_get_fuel_surchargeLTL and parcel carrier fuel surcharge percentages with effective dates
opa_get_storageCushing and SPR oil storage and inventory levels
opa_get_oil_inventoriesEIA weekly petroleum stocks
opa_get_opec_productionOPEC country-level production data
opa_get_forecastsEIA STEO energy price forecasts
opa_get_rig_countsBaker Hughes US rig count with region and observation date
opa_get_drillingRig counts, frac spreads, 30-day permits and DUCs
opa_get_well_permitsUS well permits (latest, by state, by operator)
opa_search_well_permitsState-scoped permit search by county, operator or date
opa_lookup_wellAPI-number lookup with lifecycle and monthly production
opa_get_well_activityRecent permit counts, top operators and trends
opa_get_well_productionUS well production (beta coverage)

Briefs, alerts and watches

API key; create/delete tools also need --scope write

opa_get_market_briefMulti-commodity brief: prices, 24h changes and spreads
opa_create_price_alertCreate a persistent price alert (write scope)
opa_list_price_alertsList the alerts on the account
opa_delete_price_alertDelete an alert by id (write scope)
opa_get_alert_triggersRecent alert trigger activity
opa_create_price_subscriptionCreate a recurring price watch (write scope)
opa_list_subscriptionsList the watches on the account
opa_delete_subscriptionDelete a watch by id (write scope)
opa_get_subscription_eventsPoll 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.