OilPriceAPI

Precios en tiempo real de petróleo, gas y materias primas. Más de 40 materias primas energéticas con consultas en lenguaje natural, suscripciones de precios y indicaciones para analistas.

GitHub

Prueba este MCPPatrocinado

Documentación

Servidor MCP de OilPriceAPI

Proporciona a clientes de IA compatibles datos energéticos de petróleo, gas, GNL, carbono, combustibles y relacionados con marca de tiempo de origen a través de MCP. No se necesita clave API para probar la demo limitada.

Obtén una Clave API Gratuita · Documentación · Explorador de API · Precios

Respaldado por OilPriceAPI, una API REST normalizada para paneles energéticos, herramientas de flotas y logística, flujos de trabajo marítimos e investigación de mercado.

Fuentes canónicas: Hechos públicos del producto · Registro oficial del MCP

Características

Hechos de producto revisados — una herramienta de solo lectura sin clave y un recurso estable para preguntas sobre oferta, frescura, autenticación, catálogo, derechos de datos y elegibilidad
Herramientas de datos y flujos de trabajo — valores más recientes, historial, futuros, combustibles marinos, recargos de combustible, inteligencia energética, alertas, informes de mercado y seguimientos persistentes
Recursos — el contrato de producto revisado más instantáneas de precios suscribibles
Indicaciones — plantillas de analista para informes, análisis de diferenciales, mercados de gas, costos de diésel y análisis de suministro
Lenguaje natural — solicita "petróleo brent" o "gas natural", no códigos
Catálogo amplio — petróleo, gas, carbón, productos refinados, metales, divisas, combustibles de búnker, diésel estatal y conjuntos de datos seleccionados de inteligencia energética; el acceso varía según el plan y la cuenta
Errores inteligentes — los productos no reconocidos reciben sugerencias, no respuestas silenciosas

Inicio Rápido

npx oilpriceapi-mcp

El alcance predeterminado es solo lectura. Las mutaciones de cuenta no están listadas y las llamadas directas de mutación se rechazan a menos que el alcance de escritura esté explícitamente habilitado:

npx oilpriceapi-mcp --scope write

Inspecciona el paquete sin abrir una sesión stdio de MCP:

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 genera JSON nativo del cliente, válido para copiar y pegar, para claude-desktop, claude-code, cursor, vscode, cline o windsurf. Nunca lee ni imprime la clave API configurada. Las salidas de Claude Code, VS Code y Windsurf usan sus referencias de entorno o entrada segura compatibles; Claude Desktop, Cursor y Cline usan un marcador de reemplazo local explícito. Agrega --demo para omitir por completo la configuración de la clave API. Las opciones de alcance, perfil y categoría se conservan en los argumentos del servidor generados.

¿Qué puede obtener tu agente?

Ejemplos de códigos de productos:

Código	Qué es	Uso típico del agente
`BRENT_CRUDE_USD`	Petróleo crudo Brent (global)	informes de mercado, paneles
`WTI_USD`	Petróleo crudo WTI (EE. UU.)	contexto comercial, modelos macro
`NATURAL_GAS_USD`	Gas natural Henry Hub	análisis energético
`DUTCH_TTF_EUR`	Gas TTF (Europa)	energía europea, análisis de GNL
`JKM_LNG_USD`	GNL JKM (Asia)	comercio y transporte de GNL
`EU_CARBON_EUR`	Derechos de emisión EU ETS	CBAM, cumplimiento marítimo, ESG
`DIESEL_USD`	Diésel (Costa del Golfo)	matemáticas de flotas y recargos de combustible
`JET_FUEL_USD`	Combustible de aviación	operaciones de aviación
`VLSFO_USD`	Combustible de búnker marino	cálculo de costos de viaje
`GOLD_USD`	Oro	contexto macro y de cartera

Instalación

Pruébalo sin una clave API

El servidor funciona de inmediato en modo demo sin clave — solo omite OILPRICEAPI_KEY de las configuraciones a continuación. Las herramientas de precios (opa_get_price, opa_compare_prices, opa_list_commodities, opa_market_overview) sirven los valores más recientes disponibles para un conjunto limitado de productos de demostración, y cada otra herramienta de datos explica sus requisitos de cuenta. Las respuestas de demostración están marcadas con un pie de página. Para el catálogo más amplio habilitado por cuenta, historial, futuros y alertas, obtén una clave API gratuita y agrégala a tu configuración.

Claude Desktop

Agrega a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Claude Code

Agrega al .mcp.json de tu proyecto:

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

Cursor

Agrega a .cursor/mcp.json en la raíz de tu proyecto:

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

VS Code + Cline

Agrega a .vscode/mcp.json:

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

Windsurf

Agrega a ~/.codeium/windsurf/mcp_config.json:

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

Instalación Global

npm install -g oilpriceapi-mcp

Construir el Contenedor

Las compilaciones de contenedores requieren la revisión de la fuente y la marca de tiempo del commit para que la imagen, el manifiesto de capacidades y los metadatos de compilación sean rastreables hasta el mismo 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

La imagen de ejecución usa el usuario no privilegiado node. Omite OILPRICEAPI_KEY para la demo limitada sin clave, o inyéctalo con el administrador de secretos de tu plataforma de contenedores. No incorpores credenciales en la imagen.

Variables de Entorno

Variable	Requerida	Descripción
`OILPRICEAPI_KEY`	No	Clave API de oilpriceapi.com/auth/signup. Después de la prueba principal, usa los hechos públicos del producto o la respuesta de tu cuenta para conocer la asignación gratuita actual y la ventana de reinicio. El acceso a los datos y los límites varían según el plan y la elegibilidad. Sin una clave, el servidor usa la demo limitada.
`OILPRICEAPI_BASE_URL`	No	Anula la URL base de la API (para pruebas/ensayo). Predeterminado: `https://api.oilpriceapi.com`
`OILPRICEAPI_MCP_SCOPE`	No	`read` (predeterminado) oculta y bloquea las herramientas de crear/eliminar. Establece `write` solo cuando se pretenden mutaciones de cuenta.
`OILPRICEAPI_MCP_PROFILE`	No	Perfil de inventario estable: `all` (predeterminado), `core`, `market` o `automation`.
`OILPRICEAPI_MCP_CATEGORIES`	No	Lista de permitidos de categorías separadas por comas (`core`, `market`, `automation`). Anula el perfil seleccionado.

Alcance de Herramientas y Perfiles

El alcance read incluye todas las herramientas no mutantes, incluido el historial de alertas, el listado de suscripciones y el sondeo de eventos de suscripción. Las cuatro herramientas de crear/eliminar requieren --scope write o OILPRICEAPI_MCP_SCOPE=write. Alcance, perfil o categorías desconocidos fallan de forma segura antes de que se inicie stdio.

Los perfiles reducen la sobrecarga de herramientas sin reemplazar las acciones MCP de primera clase:

Perfil	Categorías incluidas
`all`	core, market, automation
`core`	core
`market`	core, market
`automation`	core, automation

Por ejemplo, un servidor de solo lectura de precios y hechos de producto puede usar:

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

Doctor y Contrato de Capacidades

doctor verifica el runtime de Node, el punto de entrada del paquete, la accesibilidad de la API, la validez de la clave, el plan actual y las puertas de funciones informadas. doctor --demo realiza una solicitud limitada sin clave. Los fallos distinguen entre configuración faltante, 401, 402, 403, 429, tiempo de espera, DNS/TLS y respuestas 5xx del proveedor. La clave API nunca se imprime.

Cada paquete incluye build/capabilities.json. Se genera desde el mismo registro del SDK utilizado por tools/list y registra el paquete/versión/commit de la fuente, la versión mínima de Node, los alcances, los perfiles, los inventarios exactos, las anotaciones por herramienta, los requisitos de clave/elegibilidad, los recursos, los comandos y las URL de soporte. Los consumidores de sitios web y documentación deben fijar una versión del paquete, validar schemaVersion y sourceCommit, y actualizar el artefacto solo mediante una actualización explícita de dependencia. No deben extraer prosa de la CLI ni codificar recuentos de herramientas.

Registro de capacidades de API a MCP

capability-ledger.json registra una decisión explícita para cada operación en el contrato publicado de OilPriceAPI (https://api.oilpriceapi.com/openapi.json). Cada operación es exposed, nombrando la(s) herramienta(s) registrada(s), o not_exposed con una disposición (selected, deferred, alias, unsupported, internal) y una razón de una línea. Las familias agrupan operaciones en flujos de trabajo, incluidas las familias de API en vista previa que el servidor llama y que no están en el contrato canónico todavía.

npm run build && npm run check:capability-ledger compara el registro con el contrato en vivo, build/capabilities.json y las rutas REST que src/index.ts llama. Sale con 1 en caso de desviación, como una nueva operación de API sin decisión, una eliminada o una herramienta o ruta no registrada. Sale con 2 cuando no puede verificar: el contrato es inalcanzable, el manifiesto de compilación falta o la instantánea de la política de rutas es más antigua que su umbral declarado. CI lo ejecuta en cada solicitud de extracción y diariamente. Cuando una decisión cambia, incrementa ledgerVersion, agrega a changes, y enlaza ese cambio desde las notas de la versión.

Herramientas

Todas las herramientas tienen el prefijo opa_ para evitar colisiones de nombres cuando se cargan múltiples servidores MCP.

Herramienta	Descripción
`opa_get_product_facts`	Contrato de producto, oferta, frescura, autenticación, integración, derechos y licencia de datos revisados
`opa_get_price`	Precio spot actual de un solo commodity
`opa_market_overview`	Precios actuales visibles para la cuenta devueltos por la API, agrupados por categoría
`opa_compare_prices`	Comparación lado a lado de 2-5 commodities con diferencial
`opa_list_commodities`	Catálogo de commodities visible para la cuenta devuelto por la API en vivo
`opa_get_history`	Precios históricos con máximo/mínimo/promedio/cambio (día/semana/mes/año)
`opa_get_futures`	Futuros del mes más cercano (Brent, WTI, gasóleo, TTF, JKM, carbono UE)
`opa_get_futures_curve`	Curva forward completa con análisis de contango/backwardation
`opa_get_marine_fuels`	Precios de combustible de búnker por puerto y tipo de combustible (VLSFO/MGO/IFO380)
`opa_get_rig_counts`	Recuento total de equipos de perforación de Baker Hughes en EE. UU. con región y fecha de observación
`opa_get_drilling`	Instantánea de perforación: recuentos de equipos, spreads de fractura, permisos de 30 días, DUCs
`opa_get_diesel_by_state`	Precio minorista de diésel AAA para cualquier estado de EE. UU. (50 estados + DC)
`opa_get_fuel_surcharge`	Porcentajes de recargo por combustible de transportistas LTL y de paquetería con fechas de vigencia y procedencia de la fuente
`opa_get_storage`	Niveles de almacenamiento/inventario de petróleo en Cushing y SPR
`opa_get_opec_production`	Datos de producción de la OPEP a nivel de país
`opa_get_forecasts`	Pronósticos de precios de energía de EIA STEO
`opa_get_oil_inventories`	Existencias semanales de petróleo de EIA (últimas/resumen/por_producto)
`opa_get_well_permits`	Permisos de perforación de pozos en EE. UU. (últimos/por_estado/por_operador)
`opa_search_well_permits`	Búsqueda de permisos por estado, condado/operador/fecha con compuerta de frescura medida
`opa_lookup_well`	Búsqueda por número de API con ciclo de vida promovido y producción mensual exacta cuando esté disponible
`opa_get_well_activity`	Recuentos recientes de permisos/principales operadores/tendencias con advertencias explícitas de salud del estado
`opa_get_well_production`	Producción de pozos en EE. UU. — cobertura beta (resumen/estados/estado/pozo/principales_productores/tiempo_de_ciclo/cohortes)
`opa_get_spread`	Diferenciales de refinación/comercio (crack, base, margen)

Herramientas de Alertas de Precio (autenticadas)

Estas herramientas crean y gestionan alertas de precio persistentes vinculadas a tu cuenta de OilPriceAPI, por lo que requieren una clave de API (OILPRICEAPI_KEY). El motor de alertas evalúa las actualizaciones de fuentes elegibles y te notifica (por correo electrónico, además de webhook si proporcionas uno) cuando se cumple una condición.

Herramienta	Descripción
`opa_create_price_alert`	Crear una alerta persistente (commodity, operador, umbral, webhook opcional)
`opa_list_price_alerts`	Listar todas las alertas de la cuenta
`opa_delete_price_alert`	Eliminar permanentemente una alerta por id
`opa_get_alert_triggers`	Actividad reciente de activación de alertas (opcionalmente filtrada por `since`)

Herramientas de Resumen de Mercado y Suscripciones (autenticadas)

El resumen de mercado ofrece una instantánea de múltiples commodities en una sola llamada. Las suscripciones ("vigilancias") son instantáneas persistentes y recurrentes vinculadas a tu cuenta — la API registra un evento en cada intervalo, y el agente consulta nuevos eventos mediante un cursor por usuario (los eventos se consultan, no se envían — no hay conexión permanente). Estas requieren una clave de API (OILPRICEAPI_KEY). Una suscripción difiere de una alerta: una vigilancia siempre emite un evento en cada intervalo (un registro continuo), mientras que una alerta solo se activa al cruzar un umbral. Se aplican límites por cuenta de código, vigilancia y cadencia; la respuesta de la API es autoritativa y devuelve el límite actual cuando se excede.

Herramienta	Descripción
`opa_get_market_brief`	Resumen de múltiples commodities: precios, cambios en 24 h, pronósticos a 1 m, diferenciales, narrativa opcional
`opa_create_price_subscription`	Crear una vigilancia recurrente persistente (códigos, intervalo como `5m`/`1h`/`daily`)
`opa_list_subscriptions`	Listar todas las suscripciones de la cuenta
`opa_delete_subscription`	Eliminar permanentemente una suscripción por id
`opa_get_subscription_events`	Consultar nuevos eventos de vigilancia desde un cursor (`since`); devuelve instantáneas + deltas

Preguntas de Ejemplo

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

Recursos

Datos de precios suscribibles (JSON):

Recurso	URI	Descripción
Datos del Producto	`oilpriceapi://product-facts`	Contrato de producto público revisado y versionado
Brent Crudo	`price://brent`	Precio global de referencia del petróleo crudo
WTI Crudo	`price://wti`	Precio de referencia del petróleo crudo en EE. UU.
Gas Natural	`price://natural-gas`	Precio del gas natural Henry Hub en EE. UU.
Diésel	`price://diesel`	Precio promedio nacional de diésel en EE. UU.
Vista de Mercado	`price://all`	Precios actuales visibles para la cuenta desde la API

Datos del Producto y Conocimiento del Modelo

opa_get_product_facts y oilpriceapi://product-facts mejoran la precisión para una sesión MCP conectada. No reentrenan un modelo ni actualizan su conocimiento general. El servidor prefiere el contrato canónico sin clave, usa una caché acotada y etiqueta cualquier paquete de respaldo verificado por checksum con metadatos de fuente y advertencia.

Prompts

Plantillas de analista preconstruidas:

Prompt	Descripción
`daily-briefing`	Informe diario del mercado energético con precios clave y movimientos
`brent-wti-spread`	Analizar el diferencial del crudo Brent-WTI
`gas-market-analysis`	Comparar los mercados de gas natural de EE. UU. vs Europa
`commodity-report`	Informe detallado sobre un commodity específico (parametrizado)
`diesel-cost-analysis`	Comparar precios de diésel entre estados de EE. UU. para planificación de flotas
`supply-analysis`	Analizar la oferta usando producción de la OPEP, recuentos de equipos, almacenamiento

Soporte de Lenguaje Natural

Tú dices	Entendemos
"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

Desarrollo

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

Cambios Importantes en v3.0.0

El alcance predeterminado de las herramientas ahora es de solo lectura. Las herramientas de crear/eliminar alertas y suscripciones requieren --scope write o OILPRICEAPI_MCP_SCOPE=write explícitos.
La configuración inválida de alcance/perfil/categoría ahora falla antes de que se inicie MCP stdio.
Usa --list-tools --json o --capabilities --json en lugar de depender de un inventario codificado.

Cambios Importantes en v2.0.0

Todos los nombres de herramientas ahora usan el prefijo opa_ (p. ej., get_commodity_price -> opa_get_price)
Los nombres de commodities no reconocidos ahora devuelven un error con sugerencias en lugar de usar Brent por defecto silenciosamente
list_commodities ahora obtiene datos en vivo desde la API (usa la lista estática si no está disponible)

El conjunto completo de herramientas de OilPriceAPI

Mismos datos, cada stack:

Herramienta	Instalación
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`
Plugin de WordPress	widgets de precios sin código

Explora la API

🧭 Explorador interactivo: api.oilpriceapi.com/swagger — prueba cada endpoint en el navegador (modo demo, sin clave necesaria)
📜 Especificación OpenAPI: swagger.json

Política de Privacidad

Este servidor MCP se ejecuta localmente en tu máquina y solo se comunica con el servicio OilPriceAPI:

Qué se envía: las solicitudes de herramientas se traducen en llamadas HTTPS a api.oilpriceapi.com (códigos de commodities, parámetros de consulta como período de tiempo o estado, slugs de transportistas y entradas a nivel de servicio para recargos de combustible, y — para herramientas de alertas/suscripciones — los parámetros de alerta que especifiques), autenticadas con tu clave de API. No se transmite contenido de conversación — solo las entradas estructuradas de herramientas mencionadas anteriormente.
Almacenamiento de la clave de API: tu clave se almacena localmente en la configuración de tu cliente MCP (o en la variable de entorno OILPRICEAPI_KEY). Se envía solo a api.oilpriceapi.com como encabezado de Authorization.
Registro y telemetría de demanda: cada herramienta emite un evento local estructurado de acierto/fallo a stderr y atribuye su solicitud de API con el nombre de la herramienta más una forma de argumento deliberadamente aproximada. Los códigos de commodities, intervalos, códigos de estado y controles numéricos acotados pueden conservarse; texto libre, prompts, nombres, IDs, números de pozo de API, coordenadas y umbrales se reducen a provided. El registro de solicitudes de API sigue la Política de Privacidad de OilPriceAPI.
Terceros: no se comparten datos con terceros más allá de lo que describe esa política.
Modo demo: sin una clave de API, las herramientas de precios llaman al endpoint demo sin clave en el mismo host; no se involucra clave ni datos de cuenta.

Preguntas: support@oilpriceapi.com

Límite de Precios (HTTP 402)

Dónde se encuentra la línea entre lo gratuito y lo de pago para este servidor (#10):

Siempre abierto: el propio servidor MCP (MIT), configuración, documentación, descubrimiento (listado de herramientas) y modo demo sin clave para evaluación de bajo volumen.
Clave API: use los datos públicos del producto y la respuesta de su cuenta para la prueba actual, asignación, ventana de reinicio y derecho de acceso al conjunto de datos. El modo demo sin clave sigue disponible para un conjunto de datos limitado.
Detrás del muro de pago: uso de alto volumen y conjuntos de datos premium (futuros, inteligencia energética, permisos/producción de pozos, alertas a escala). Cuando una solicitud cruza ese límite, la API devuelve un HTTP 402/403/429 estándar con el límite exacto o la puerta de función en el cuerpo, y este servidor muestra ese mensaje más un enlace de actualización — los agentes reciben una parada legible por máquina, nunca un fallo silencioso.
Protocolo x402: micropagos criptográficos por solicitud a través del protocolo x402 no están soportados actualmente — el pago es mediante plan de cuenta (Stripe), autenticado con su clave API.