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 · Documentation · API Explorer · Pricing

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.

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: