mcp-server

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

[![npm](https://img.shields.io/npm/v/oilpriceapi-mcp)](https://www.npmjs.com/package/oilpriceapi-mcp)
[![Downloads](https://img.shields.io/npm/dm/oilpriceapi-mcp)](https://www.npmjs.com/package/oilpriceapi-mcp)
[![license](https://img.shields.io/npm/l/oilpriceapi-mcp)](LICENSE)

**[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](https://oilpriceapi.com), a normalized REST API for energy dashboards, fleet and logistics tools, maritime workflows, and market research.

**Canonical sources:** [Public product facts](https://api.oilpriceapi.com/product-facts.json) · [Official MCP Registry record](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.OilpriceAPI%2Fmcp-server/versions/latest)

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

```bash
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:

```bash
npx oilpriceapi-mcp --scope write
```

Inspect the package without opening an MCP stdio session:

```bash
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:

| Code              | What it is               | Typical agent use              |
| ----------------- | ------------------------ | ------------------------------ |
| `BRENT_CRUDE_USD` | Brent crude (global)     | market briefings, dashboards   |
| `WTI_USD`         | WTI crude (US)           | trading context, macro models  |
| `NATURAL_GAS_USD` | Henry Hub natural gas    | energy analytics               |
| `DUTCH_TTF_EUR`   | TTF gas (Europe)         | European energy, LNG analysis  |
| `JKM_LNG_USD`     | JKM LNG (Asia)           | LNG trading & shipping         |
| `EU_CARBON_EUR`   | EU ETS carbon allowances | CBAM, maritime compliance, ESG |
| `DIESEL_USD`      | Diesel (Gulf Coast)      | fleet & fuel-surcharge math    |
| `JET_FUEL_USD`    | Jet fuel                 | aviation ops                   |
| `VLSFO_USD`       | Marine bunker fuel       | voyage costing                 |
| `GOLD_USD`        | Gold                     | macro & portfolio context      |

## 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](https://oilpriceapi.com/auth/signup?utm_source=mcp-demo) 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):

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

### Claude Code

Add to your project's `.mcp.json`:

```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:

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

### VS Code + Cline

Add to `.vscode/mcp.json`:

```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`:

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

### Global Install

```bash
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:

```bash
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

| Variable                     | Required | Description                                                                                                                                                                                                                                                                                            |
| ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `OILPRICEAPI_KEY`            | No       | API key from [oilpriceapi.com/auth/signup](https://www.oilpriceapi.com/auth/signup?utm_source=npm&utm_medium=mcp&utm_campaign=readme). After the core trial, use the [public product facts](https://api.oilpriceapi.com/product-facts.json) or your account response for the current Free allowance and reset window. Dataset access and limits vary by plan and entitlement. Without a key, the server uses the limited demo. |
| `OILPRICEAPI_BASE_URL`       | No       | Override API base URL (for staging/testing). Default: `https://api.oilpriceapi.com`                                                                                                                                                                                                                    |
| `OILPRICEAPI_MCP_SCOPE`      | No       | `read` (default) hides and blocks create/delete tools. Set `write` only when account mutations are intended.                                                                                                                                                                                           |
| `OILPRICEAPI_MCP_PROFILE`    | No       | Stable inventory profile: `all` (default), `core`, `market`, or `automation`.                                                                                                                                                                                                                          |
| `OILPRICEAPI_MCP_CATEGORIES` | No       | Comma-separated category allowlist (`core`, `market`, `automation`). Overrides the selected profile.                                                                                                                                                                                                   |

## 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:

| Profile      | Included categories      |
| ------------ | ------------------------ |
| `all`        | core, market, automation |
| `core`       | core