OilPriceAPI — Real-Time Oil, Gas & Commodity Prices for AI Agents

OilPriceAPI MCP Server

通过 MCP，为兼容的 AI 客户端提供带来源时间戳的石油、天然气、LNG、碳、燃料及相关能源数据。试用有限的演示版无需 API 密钥。

获取免费 API 密钥 · 文档 · API Explorer · 定价

由 OilPriceAPI 提供支持。这是一个标准化的 REST API，适用于能源仪表板、车队与物流工具、海事工作流和市场研究。

权威来源： 公开产品信息 · 官方 MCP Registry 记录

功能

• 经审核的产品信息 — 无需密钥的只读工具和稳定资源，可回答有关套餐、数据新鲜度、身份验证、目录、权限和数据权利的问题
• 数据与工作流工具 — 最新值、历史数据、期货、船用燃料、燃料附加费、能源情报、提醒、市场简报和持久监控
• 资源 — 经审核的产品契约，以及可订阅的价格快照
• 提示词 — 用于简报、价差分析、天然气市场、柴油成本和供应分析的分析师模板
• 自然语言 — 可询问“brent oil”或“natural gas”，无需使用代码
• 丰富的目录 — 石油、天然气、煤炭、精炼产品、金属、外汇、船用燃料、各州柴油以及精选能源情报数据集；可访问内容因套餐和账户而异
• 智能错误处理 — 对无法识别的商品提供建议，而不是静默回退

快速开始

npx oilpriceapi-mcp

默认范围为只读。账户变更操作不会列出，除非明确启用写入范围，否则直接调用变更操作会遭到拒绝：

npx oilpriceapi-mcp --scope write

无需开启 MCP stdio 会话即可检查软件包：

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 会生成适用于客户端的 JSON，可直接复制粘贴到 claude-desktop、claude-code、cursor、vscode、cline 或 windsurf。 它绝不会读取或打印已配置的 API 密钥。Claude Code、VS Code 和 Windsurf 输出使用其支持的环境变量或安全输入引用； Claude Desktop、Cursor 和 Cline 则使用明确的本地替换标记。 添加 --demo 可完全省略 API 密钥配置。生成的服务端参数会保留范围、配置文件和类别选项。

Agent 能获取什么？

商品代码示例：

Code	内容	Agent 的典型用途
BRENT_CRUDE_USD	布伦特原油（全球）	市场简报、仪表板
WTI_USD	WTI 原油（美国）	交易背景、宏观模型
NATURAL_GAS_USD	Henry Hub 天然气	能源分析
DUTCH_TTF_EUR	TTF 天然气（欧洲）	欧洲能源、LNG 分析
JKM_LNG_USD	JKM LNG（亚洲）	LNG 交易与运输
EU_CARBON_EUR	EU ETS 碳排放配额	CBAM、海事合规、ESG
DIESEL_USD	柴油（墨西哥湾沿岸）	车队与燃料附加费计算
JET_FUEL_USD	航空燃油	航空运营
VLSFO_USD	船用燃料	航程成本核算
GOLD_USD	黄金	宏观与投资组合分析

安装

无需 API 密钥即可试用

该服务开箱即用，支持无密钥演示模式——只需在以下配置中省略 OILPRICEAPI_KEY。价格工具（opa_get_price、opa_compare_prices、opa_list_commodities、opa_market_overview）会提供有限演示商品集的最新可用价格，其他数据工具则会说明账户要求。演示响应会附带页脚标记。如需使用更丰富的账户可用目录、历史数据、期货和警报，获取免费 API 密钥并将其添加到配置中。

Claude Desktop

将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

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

Claude Code

将以下内容添加到项目的 .mcp.json：

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

Cursor

将以下内容添加到项目根目录下的 .cursor/mcp.json：

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

VS Code + Cline

将以下内容添加到 .vscode/mcp.json：

{
  "servers": {
    "oilpriceapi": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "oilpriceapi-mcp"],
      "env": {
        "OILPRICEAPI_KEY": "your-api-key-here"
      }
    }
  }
}

Windsurf

将以下内容添加到 ~/.codeium/windsurf/mcp_config.json：

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

全局安装

npm install -g oilpriceapi-mcp

构建容器

构建容器需要提供源代码版本和提交时间戳，以确保映像、 能力清单和构建元数据均可追溯到同一份检出版本：

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

运行时映像使用非特权 node 用户。对于有限的无密钥演示模式，请省略 OILPRICEAPI_KEY；也可以通过容器平台的密钥管理器注入该密钥。请勿将凭据烘焙到映像中。

传输方式

此服务仅在本地通过 stdio 运行。其 MCP Registry 记录列出了 npm 软件包，不包含远程端点。

托管连接器 https://mcp.oilpriceapi.com/mcp 不是此服务。 它是另一套规模较小的 energy_* 工具，支持 OAuth 账户关联， 供无法启动本地进程的托管客户端使用。要使用完整的 opa_* 工具集，请使用此软件包。

环境变量

变量	必填	描述
OILPRICEAPI_KEY	否	从 oilpriceapi.com/auth/signup 获取的 API 密钥。核心试用期结束后，请查看 公开产品信息 或账户响应，了解当前免费额度和重置周期。数据集访问权限和限额因套餐及授权而异。未提供密钥时，服务将使用受限演示模式。
OILPRICEAPI_BASE_URL	否	覆盖 API 基础 URL（用于暂存／测试）。默认值：https://api.oilpriceapi.com
OILPRICEAPI_MCP_SCOPE	否	read（默认）会隐藏并禁用创建／删除工具。仅在需要修改账户时设置为 write。
OILPRICEAPI_MCP_PROFILE	否	稳定的工具清单配置：all（默认）、core、market 或 automation。
OILPRICEAPI_MCP_CATEGORIES	否	以逗号分隔的类别允许列表（core、market、automation）。会覆盖所选配置。

工具范围与配置

read 范围包含所有不会修改数据的工具，包括警报历史记录、 订阅列表和订阅事件轮询。四个创建／删除工具需要使用 --scope write 或设置 OILPRICEAPI_MCP_SCOPE=write。未知的范围、 配置或类别值会在 stdio 启动前触发安全失败。

配置可减少工具过载，但不会取代一等 MCP 操作：

配置	包含的类别
all	core、market、automation
core	core
market	core、market
automation	core、automation

例如，可按如下方式配置只读价格与产品信息服务：

{
  "command": "npx",
  "args": ["-y", "oilpriceapi-mcp", "--scope", "read", "--profile", "core"]
}

Doctor 和能力契约

doctor 会检查 Node 运行时、软件包入口点、API 可达性、密钥有效性、当前套餐和已报告的功能门控。doctor --demo 会执行一次有界的无密钥请求。失败情况会区分配置缺失、401、402、403、429、超时、DNS/TLS 和上游 5xx 响应。API 密钥绝不会被打印。

每个软件包都包含 build/capabilities.json。它由与 tools/list 相同的 SDK 注册表生成，并记录软件包/版本/源代码提交、最低 Node 版本、作用域、配置、精确清单、各工具注解、密钥/授权要求、资源、命令和支持 URL。网站和文档使用方应固定软件包版本，验证 schemaVersion 和 sourceCommit，并且只通过显式升级依赖来更新此构件。它们不应抓取 CLI 文案或硬编码工具数量。

API 到 MCP 能力清单

capability-ledger.json 会为已发布的 OilPriceAPI 契约（https://api.oilpriceapi.com/openapi.json）中的每个操作记录明确的决策。每个操作要么标记为 exposed 并列出已注册的工具，要么标记为 not_exposed，并注明处置方式（selected、deferred、alias、unsupported、internal）和一行说明。各操作系列按工作流分组，其中也包括服务端调用但尚未纳入规范契约的预览 API 系列。

npm run build && npm run check:capability-ledger 会将清单与实时契约、build/capabilities.json 以及 src/index.ts 调用的 REST 路径进行比对。若存在偏差，例如新增 API 操作未作决策、操作已移除，或工具或路径未记录，它会以状态码 1 退出。若无法执行检查，例如契约无法访问、构建清单缺失，或路由策略快照早于其声明的阈值，它会以状态码 2 退出。CI 会在每个拉取请求和每日运行此检查。决策发生变化时，请递增 ledgerVersion，在 changes 中追加记录，并在发行说明中链接该变更。

工具

为避免加载多个 MCP 服务时发生名称冲突，所有工具名称均以 opa_ 为前缀。

工具	描述
opa_get_product_facts	经审核的产品、报价、数据新鲜度、身份验证、集成、权益和数据权利合同
opa_get_price	单种大宗商品的当前现货价格
opa_market_overview	API 返回的账户可见当前价格，按类别分组
opa_compare_prices	2-5 种大宗商品的并排比较及价差
opa_list_commodities	实时 API 返回的账户可见大宗商品目录
opa_get_history	历史价格及最高价/最低价/均价/变动（按日/周/月/年）
opa_get_history_range	1-5 种大宗商品在开始/结束日期范围内的带日期价格数据，按小时至按月，支持分页
opa_get_futures	近月期货（Brent、WTI、gasoil、TTF、JKM、EU carbon）
opa_get_futures_curve	完整远期曲线及升水/贴水分析
opa_get_futures_history	Brent、WTI、NYMEX natural gas 按合约月份划分的 OHLC 历史数据，最多 730 天
opa_get_marine_fuels	按港口和燃料类型（VLSFO/MGO/IFO380）划分的船用燃料价格
opa_get_marine_ports	加油港目录（UN/LOCODE、地区、燃料服务）或单个港口的近期价格
opa_get_marine_fuel_history	单个港口的一种船用燃料每日历史数据；需付费订阅或有效试用
opa_get_rig_counts	Baker Hughes 美国钻机总数，含地区和观测日期
opa_get_drilling	钻井快照：钻机数量、压裂作业队、30 天许可证、DUC
opa_get_diesel_by_state	美国任一州（50 个州及 DC）的 AAA 零售柴油价格
opa_get_fuel_surcharge	LTL 和包裹承运商燃油附加费百分比，含生效日期和来源溯源
opa_get_storage	Cushing 和 SPR 石油储存/库存水平
opa_get_opec_production	OPEC 各国生产数据
opa_get_forecasts	EIA STEO 能源价格预测
opa_get_oil_inventories	EIA 每周石油库存（最新/摘要/按产品）
opa_get_well_permits	美国油井钻探许可证（最新/按州/按运营商）
opa_search_well_permits	按州限定的许可证搜索，可按县/运营商/日期筛选，并设有经测量的数据新鲜度门槛
opa_lookup_well	按 API 编号查询，提供提升后的生命周期信息，并在可用时提供精确的月度产量
opa_get_well_activity	近期许可证数量/顶级运营商/趋势，并明确提示州级运行状况
opa_get_well_production	美国油井产量 — 测试版覆盖范围（摘要/各州/州/油井/顶级生产商/周期时间/群组）
opa_get_spread	裂解价差（类型、原油）、基差（货币对或所有货币对）、利润率（指数）；可选日期范围历史数据
opa_get_natural_gas_hubs	美国实物天然气枢纽价格，以 Henry Hub 为基准（Waha、SoCal、Chicago 等）
opa_get_data_quality	OilPriceAPI 各数据序列自身的数据质量等级（完整性、新鲜度等）
opa_get_account_status	已配置密钥对应的套餐等级、请求用量、剩余配额和重置日期
opa_get_plans	当前订阅套餐：价格、请求限制和包含的功能

价格提醒工具（需身份验证）

这些工具会创建和管理与 OilPriceAPI 账户关联的持久价格提醒，因此需要 API 密钥（OILPRICEAPI_KEY）。提醒引擎会评估符合条件的来源更新，并在满足条件时通过电子邮件通知你；如果你提供了 webhook，也会通过 webhook 通知。

工具	描述
opa_create_price_alert	创建持久提醒（商品、运算符、阈值、可选 webhook）
opa_list_price_alerts	列出账户上的所有提醒
opa_delete_price_alert	按 id 永久删除提醒
opa_get_alert_triggers	最近的提醒触发活动（可选按 since 筛选）

市场简报与订阅工具（需身份验证）

市场简报会通过一次调用提供多种商品的快照。订阅（“观察”）是与你的账户关联的持久、定期快照——API 每个间隔都会记录一个事件，而 Agent 会通过每位用户的游标轮询新事件（事件通过轮询获取，不会主动推送——没有始终保持连接）。这些工具需要 API 密钥（OILPRICEAPI_KEY）。订阅与提醒不同：观察会在每个间隔都生成一个事件（持续记录），而提醒只会在价格越过阈值时触发。每个账户的代码、观察和频率均有限制；超出限制时，以 API 响应为准，其中会返回当前限制。

工具	描述
opa_get_market_brief	多商品简报：价格、24 小时变化、1 个月预测、价差及可选说明
opa_create_price_subscription	创建持久的定期观察（代码、间隔，如 5m/1h/daily）
opa_list_subscriptions	列出账户上的所有订阅
opa_delete_subscription	按 id 永久删除订阅
opa_get_subscription_events	通过游标（since）轮询新的观察事件；返回快照和变化

示例问题

"What's the current Brent oil price?"
"Compare Brent and WTI crude"
"Show me oil prices for the past month"
"What's diesel cost in California vs Texas?"
"Give me a market overview of refined products"
"What's the Brent futures curve look like?"
"How many rigs are active in the US?"
"What are OPEC production levels?"
"What are bunker fuel prices in Singapore?"
"Show me Cushing storage levels"
"What were the latest EIA crude oil inventories?"
"How many well permits were issued in Texas?"
"What's the current 3-2-1 crack spread?"
"What's the UPS ground fuel surcharge?"
"Show me the gasoil futures curve"

资源

可订阅的价格数据（JSON）：

资源	URI	描述
产品事实	oilpriceapi://product-facts	经审核、带版本的公开产品契约
Brent 原油	price://brent	全球基准原油价格
WTI 原油	price://wti	美国基准原油价格
天然气	price://natural-gas	美国 Henry Hub 天然气价格
柴油	price://diesel	美国全国平均柴油价格
市场视图	price://all	API 中账户可见的当前价格

产品事实与模型知识

opa_get_product_facts 和 oilpriceapi://product-facts 可提高已连接 MCP 会话的准确性。它们不会重新训练模型，也不会更新模型的通用知识。服务端优先使用规范的无密钥契约，采用有界缓存，并为任何通过校验和验证的软件包回退内容标注来源和警告元数据。

提示词

预置分析模板：

提示词	描述
daily-briefing	能源市场每日简报，包含关键价格和涨跌品种
brent-wti-spread	分析布伦特原油与 WTI 原油价差
gas-market-analysis	对比美国与欧洲的天然气市场
commodity-report	特定大宗商品的详细报告（可设置参数）
diesel-cost-analysis	对比美国各州的柴油价格，为车队规划提供参考
supply-analysis	利用 OPEC 产量、钻机数量和库存分析供应情况

自然语言支持

你说	我们理解
"brent oil", "brent crude"	BRENT_CRUDE_USD
"wti", "us oil"	WTI_USD
"natural gas", "henry hub"	NATURAL_GAS_USD
"european gas", "ttf"	DUTCH_TTF_EUR
"diesel"	DIESEL_USD
"gold"	GOLD_USD
"jet fuel", "aviation fuel"	JET_FUEL_USD
"carbon", "carbon credits"	EU_CARBON_EUR

开发

npm install
npm run build
npm test
OILPRICEAPI_KEY=your-key node build/index.js

v3.0.0 中的破坏性变更

• 默认工具范围现为只读。创建/删除告警和订阅的工具需要显式设置 --scope write 或 OILPRICEAPI_MCP_SCOPE=write。
• 无效的范围/配置文件/类别配置现在会在 MCP stdio 启动前导致失败。
• 请使用 --list-tools --json 或 --capabilities --json，不要依赖硬编码的清单。

v2.0.0 中的破坏性变更

• 所有工具名称现在都使用 opa_ 前缀（例如，get_commodity_price -> opa_get_price）
• 无法识别的大宗商品名称现在会返回带有建议的错误，而不是静默地默认使用布伦特原油
• list_commodities 现在会从 API 获取实时数据（若不可用，则回退到静态列表）

OilPriceAPI 全套工具

相同数据，支持各种技术栈：

工具	安装
Python SDK	pip install oilpriceapi
Node/TypeScript SDK	npm install oilpriceapi
PHP SDK	composer require oilpriceapi/oilpriceapi
Go SDK	go get github.com/OilpriceAPI/oilpriceapi-go
WordPress plugin	无代码价格组件

探索 API

• 🧭 交互式浏览器：api.oilpriceapi.com/swagger — 在浏览器中试用每个端点（演示模式，无需密钥）
• 📜 OpenAPI 规范：swagger.json

隐私政策

此 MCP 服务在你的计算机上本地运行，仅与 OilPriceAPI 服务通信：

• 发送的内容：工具请求会转换为发往 api.oilpriceapi.com 的 HTTPS 调用（商品代码、时间段或州等查询参数、燃油附加费所需的承运商标识和服务级别输入，以及告警／订阅工具所需的你指定的告警参数），并使用你的 API 密钥进行身份验证。不会传输任何对话内容——仅传输上述结构化工具输入。
• API 密钥存储：你的密钥存储在 MCP 客户端的配置中（或 OILPRICEAPI_KEY 环境变量中）。它只会作为 Authorization 标头发送到 api.oilpriceapi.com。
• 日志记录和需求遥测：每个工具都会向 stderr 输出本地结构化命中／未命中事件，并在 API 请求中附带工具名称和经过有损处理的参数形式。商品代码、间隔、州代码和有界数值控制项可能会被保留；自由文本、提示词、名称、ID、API 油井编号、坐标和阈值会简化为 provided。API 请求日志遵循 OilPriceAPI 隐私政策。
• 第三方：除该政策所述内容外，不会与第三方共享任何数据。
• 演示模式：没有 API 密钥时，价格工具会调用同一主机上的免密演示端点；不会涉及密钥或账户数据。

如有疑问，请联系：[email protected]

定价边界（HTTP 402）

此服务的免费／付费界线所在位置（#10）：

• 始终开放：MCP 服务本身（MIT）、设置、文档、发现（工具列表）以及供低频评估使用的免密演示模式。
• API 密钥：请通过公开产品信息和你的账户响应，查看当前试用、额度、重置周期和数据集权限。免密演示模式仍可用于有限的数据集。
• 付费墙之后：高频使用和高级数据集（期货、能源情报、油井许可证／产量、大规模告警）。请求超出此边界时，API 会返回标准的 HTTP 402/403/429，响应正文中包含确切的限额或功能限制，而此服务会显示该消息和升级链接——Agent 会收到机器可读的停止信号，不会遇到静默失败。
• x402 协议：目前不支持通过 x402 协议按请求进行加密货币微支付——付费采用账户套餐（Stripe），并使用你的 API 密钥进行身份验证。

许可证

MIT

链接

• OilPriceAPI
• API 文档
• 定价
• MCP 协议

也提供以下版本

• Python SDK - 支持 Pandas 集成的 Python 客户端
• Node.js SDK - TypeScript/JavaScript SDK
• Go SDK - 符合 Go 惯例的客户端
• OpenBB 集成 - OpenBB Platform 提供方