OilpriceAPI MCP

OilPriceAPI MCP Server

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](https://www.oilpriceapi.com/auth/signup?utm_source=mcp-readme) · [Documentation](https://docs.oilpriceapi.com) · [API Explorer](https://api.oilpriceapi.com/swagger) · [Pricing](https://www.oilpriceapi.com/pricing?utm_source=mcp-readme)

Backed by OilPriceAPI, 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

Features

• Reviewed product facts — a keyless read-only tool and stable resource for offer, freshness, authentication, catalog, entitlement, and data-rights questions
• Data and workflow tools — latest values, history, futures, marine fuels, fuel surcharges, energy intelligence, alerts, market briefs, and persistent watches
• Resources — the reviewed product contract plus subscribable price snapshots
• Prompts — analyst templates for briefings, spread analysis, gas markets, diesel costs, and supply analysis
• Natural language — ask for "brent oil" or "natural gas", not codes
• Broad catalog — oil, gas, coal, refined products, metals, forex, bunker fuels, state diesel, and selected energy-intelligence datasets; access varies by plan and account
• Smart errors — unrecognized commodities get suggestions, not silent fallbacks

Quick Start

npx oilpriceapi-mcp

The default scope is read-only. Account mutations are not listed and direct mutation calls are rejected unless write scope is explicitly enabled:

npx oilpriceapi-mcp --scope write

Inspect the package without opening an MCP stdio session:

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

--config generates client-native, copy/paste-valid JSON for claude-desktop, claude-code, cursor, vscode, cline, or windsurf. It never reads or prints the configured API key. Claude Code, VS Code, and Windsurf outputs use their supported environment or secure-input references; Claude Desktop, Cursor, and Cline use an explicit local replacement marker. Add --demo to omit API-key configuration entirely. Scope, profile, and category options are preserved in the generated server arguments.

What can your agent get?

Example commodity codes:

Installation

Try it without an API key

The server works out of the box in keyless demo mode — just omit OILPRICEAPI_KEY from 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 key and add it to your config.

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

Build the Container

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 unprivileged node user. Omit OILPRICEAPI_KEY for the limited keyless demo, or inject it with your container platform's secret manager. Do not bake credentials into the image.

Transport

This server runs locally over stdio only. Its MCP Registry record lists the npm package and no remote endpoint.

The hosted connector at https://mcp.oilpriceapi.com/mcp is not this server. It is a separate, smaller set of energy_* tools with OAuth account linking, used by hosted clients that cannot launch a local process. Use this package for the full opa_* tool set.

Environment Variables

Tool Scope and Profiles

read scope includes all non-mutating tools, including alert history, subscription listing, and subscription event polling. The four create/delete tools require --scope write or OILPRICEAPI_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"] }

Doctor and Capability Contract

doctor checks the Node runtime, package entry point, API reachability, key validity, current plan, and reported feature gates. doctor --demo performs 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 includes build/capabilities.json. It is generated from the same SDK registry used by tools/list and 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, validate schemaVersion and sourceCommit, and update the artifact only through an explicit dependency upgrade. They should not scrape CLI prose or hard-code tool counts.

API-to-MCP capability ledger

capability-ledger.json records an explicit decision for every operation in the published OilPriceAPI contract (https://api.oilpriceapi.com/openapi.json). Each operation is either exposed, naming the registered tool(s), or not_exposed with a disposition (selected, deferred, alias, unsupported, internal) and a one-line reason. Families group operations into workflows, including p