OilPriceAPI

Servidor MCP OilPriceAPI

Forneça a clientes de IA compatíveis dados de petróleo, gás, GNL, carbono, combustíveis e energia relacionados com carimbo de data/hora de origem por meio do MCP. Nenhuma chave de API é necessária para experimentar a demo limitada.

Obtenha uma Chave de API Gratuita · Documentação · Explorador de API · Preços

Suportado por OilPriceAPI, uma API REST normalizada para painéis de energia, ferramentas de frota e logística, fluxos de trabalho marítimos e pesquisa de mercado.

Fontes canônicas: Fatos públicos do produto · Registro oficial do MCP Registry

Recursos

• Fatos revisados do produto — uma ferramenta somente leitura sem chave e um recurso estável para perguntas sobre oferta, atualização, autenticação, catálogo, direito de uso e direitos de dados
• Ferramentas de dados e fluxo de trabalho — valores mais recentes, histórico, futuros, combustíveis marítimos, sobretaxas de combustível, inteligência energética, alertas, briefings de mercado e monitoramentos persistentes
• Recursos — o contrato de produto revisado mais snapshots de preços assináveis
• Prompts — modelos de analista para briefings, análise de spreads, mercados de gás, custos de diesel e análise de oferta
• Linguagem natural — peça "petróleo brent" ou "gás natural", não códigos
• Catálogo amplo — petróleo, gás, carvão, produtos refinados, metais, câmbio, combustíveis de bunker, diesel estadual e conjuntos de dados selecionados de inteligência energética; o acesso varia por plano e conta
• Erros inteligentes — commodities não reconhecidas recebem sugestões, não fallbacks silenciosos

Início Rápido

npx oilpriceapi-mcp

O escopo padrão é somente leitura. Mutações de conta não são listadas e chamadas diretas de mutação são rejeitadas, a menos que o escopo de escrita seja explicitamente habilitado:

npx oilpriceapi-mcp --scope write

Inspecione o pacote sem abrir uma sessão 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 gera JSON nativo do cliente, válido para copiar/colar, para claude-desktop, claude-code, cursor, vscode, cline ou windsurf. Ele nunca lê ou imprime a chave de API configurada. As saídas do Claude Code, VS Code e Windsurf usam referências de ambiente suportadas ou de entrada segura; Claude Desktop, Cursor e Cline usam um marcador explícito de substituição local. Adicione --demo para omitir a configuração da chave de API inteiramente. Opções de escopo, perfil e categoria são preservadas nos argumentos do servidor gerados.

O que seu agente pode obter?

Exemplos de códigos de commodities:

Código	O que é	Uso típico do agente
BRENT_CRUDE_USD	Brent bruto (global)	briefings de mercado, painéis
WTI_USD	WTI bruto (EUA)	contexto de negociação, modelos macro
NATURAL_GAS_USD	Gás natural Henry Hub	análise de energia
DUTCH_TTF_EUR	Gás TTF (Europa)	energia europeia, análise de GNL
JKM_LNG_USD	GNL JKM (Ásia)	negociação e transporte de GNL
EU_CARBON_EUR	Licenças de carbono EU ETS	CBAM, conformidade marítima, ESG
DIESEL_USD	Diesel (Costa do Golfo)	matemática de frota e sobretaxa de combustível
JET_FUEL_USD	Combustível de aviação	operações de aviação
VLSFO_USD	Combustível bunker marítimo	custeio de viagem
GOLD_USD	Ouro	contexto macro e de portfólio

Instalação

Experimente sem uma chave de API

O servidor funciona imediatamente no modo demo sem chave — basta omitir OILPRICEAPI_KEY das configurações abaixo. As ferramentas de preço (opa_get_price, opa_compare_prices, opa_list_commodities, opa_market_overview) servem os valores mais recentes disponíveis para um conjunto limitado de commodities de demonstração, e todas as outras ferramentas de dados explicam seus requisitos de conta. As respostas da demo são marcadas com um rodapé. Para o catálogo mais amplo habilitado por conta, histórico, futuros e alertas, obtenha uma chave de API gratuita e adicione-a à sua configuração.

Claude Desktop

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

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

Claude Code

Adicione ao .mcp.json do seu projeto:

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

Cursor

Adicione a .cursor/mcp.json na raiz do seu projeto:

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

VS Code + Cline

Adicione a .vscode/mcp.json:

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

Windsurf

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

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

Instalação Global

npm install -g oilpriceapi-mcp

Construa o Contêiner

As construções de contêiner exigem a revisão da fonte e o carimbo de data/hora do commit para que a imagem, o manifesto de capacidades e os metadados de construção sejam rastreáveis ao mesmo 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

A imagem de runtime usa o usuário não privilegiado node. Omita OILPRICEAPI_KEY para a demo limitada sem chave, ou injete-a com o gerenciador de segredos da sua plataforma de contêiner. Não grave credenciais na imagem.

Variáveis de Ambiente

Variável	Obrigatória	Descrição
OILPRICEAPI_KEY	Não	Chave de API de oilpriceapi.com/auth/signup. Após o teste principal, use os fatos públicos do produto ou a resposta da sua conta para a permissão gratuita atual e a janela de redefinição. O acesso e os limites do conjunto de dados variam por plano e direito. Sem uma chave, o servidor usa a demo limitada.
OILPRICEAPI_BASE_URL	Não	Substitui a URL base da API (para testes/staging). Padrão: https://api.oilpriceapi.com
OILPRICEAPI_MCP_SCOPE	Não	read (padrão) oculta e bloqueia ferramentas de criar/excluir. Defina write somente quando mutações de conta forem pretendidas.
OILPRICEAPI_MCP_PROFILE	Não	Perfil de inventário estável: all (padrão), core, market ou automation.
OILPRICEAPI_MCP_CATEGORIES	Não	Lista de permissões de categorias separadas por vírgula (core, market, automation). Substitui o perfil selecionado.

Escopo e Perfis de Ferramentas

O escopo read inclui todas as ferramentas não mutáveis, incluindo histórico de alertas, listagem de assinaturas e sondagem de eventos de assinatura. As quatro ferramentas de criar/excluir exigem --scope write ou OILPRICEAPI_MCP_SCOPE=write. Escopo, perfil ou valores de categoria desconhecidos falham de forma fechada antes do início do stdio.

Os perfis reduzem a sobrecarga de ferramentas sem substituir ações MCP de primeira classe:

Perfil	Categorias incluídas
all	core, market, automation
core	core
market	core, market
automation	core, automation

Por exemplo, um servidor somente leitura de preços e fatos do produto pode usar:

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

Contrato de Doctor e Capacidades

doctor verifica o runtime do Node, o ponto de entrada do pacote, a acessibilidade da API, a validade da chave, o plano atual e os portões de recursos relatados. doctor --demo realiza uma solicitação limitada sem chave. As falhas distinguem configuração ausente, 401, 402, 403, 429, timeout, DNS/TLS e respostas 5xx upstream. A chave de API nunca é impressa.

Todo pacote inclui build/capabilities.json. Ele é gerado a partir do mesmo registro de SDK usado por tools/list e registra o pacote/versão/commit da fonte, versão mínima do Node, escopos, perfis, inventários exatos, anotações por ferramenta, requisitos de chave/direito, recursos, comandos e URLs de suporte. Consumidores de site e documentação devem fixar uma versão do pacote, validar schemaVersion e sourceCommit, e atualizar o artefato somente por meio de uma atualização explícita de dependência. Eles não devem extrair prosa de CLI ou codificar contagens de ferramentas.

Registro de capacidades API-para-MCP

capability-ledger.json registra uma decisão explícita para cada operação no contrato publicado do OilPriceAPI (https://api.oilpriceapi.com/openapi.json). Cada operação é exposed, nomeando a(s) ferramenta(s) registrada(s), ou not_exposed com uma disposição (selected, deferred, alias, unsupported, internal) e uma razão de uma linha. Famílias agrupam operações em fluxos de trabalho, incluindo famílias de API de pré-visualização que o servidor chama e que não estão no contrato canônico ainda.

npm run build && npm run check:capability-ledger compara o registro com o contrato ao vivo, build/capabilities.json e os caminhos REST que src/index.ts chama. Ele sai com 1 em caso de desvio, como uma nova operação de API sem decisão, uma removida, ou uma ferramenta ou caminho não registrado. Ele sai com 2 quando não pode verificar: o contrato está inacessível, o manifesto de construção está ausente, ou o snapshot da política de rota é mais antigo que seu limite declarado. CI o executa em cada pull request e diariamente. Quando uma decisão muda, aumente ledgerVersion, anexe a changes, e vincule essa mudança nas notas de versão.

Ferramentas

Todas as ferramentas são prefixadas com opa_ para evitar colisões de nomes quando vários servidores MCP são carregados.

Ferramenta	Descrição
opa_get_product_facts	Contrato de produto, oferta, frescor, autenticação, integração, direito de uso e direitos de dados revisados
opa_get_price	Preço spot atual para uma única commodity
opa_market_overview	Preços atuais visíveis na conta retornados pela API, agrupados por categoria
opa_compare_prices	Comparação lado a lado de 2 a 5 commodities com spread
opa_list_commodities	Catálogo de commodities visível na conta retornado pela API ao vivo
opa_get_history	Preços históricos com alta/baixa/média/variação (dia/semana/mês/ano)
opa_get_futures	Futuros do primeiro mês (Brent, WTI, gasóleo, TTF, JKM, carbono da UE)
opa_get_futures_curve	Curva futura completa com análise de contango/backwardation
opa_get_marine_fuels	Preços de combustível de bunker por porto e tipo de combustível (VLSFO/MGO/IFO380)
opa_get_rig_counts	Contagem total de sondas dos EUA da Baker Hughes com região e data de observação
opa_get_drilling	Instantâneo de perfuração: contagens de sondas, spreads de fraturamento, permissões de 30 dias, DUCs
opa_get_diesel_by_state	Preço médio de diesel no varejo da AAA para qualquer estado dos EUA (50 estados + DC)
opa_get_fuel_surcharge	Percentuais de sobretaxa de combustível para transportadoras LTL e de encomendas com datas de vigência e proveniência da fonte
opa_get_storage	Níveis de armazenamento/estoque de petróleo em Cushing e SPR
opa_get_opec_production	Dados de produção da OPEP em nível de país
opa_get_forecasts	Previsões de preços de energia do EIA STEO
opa_get_oil_inventories	Estoques semanais de petróleo do EIA (mais recente/resumo/por_produto)
opa_get_well_permits	Permissões de perfuração de poços nos EUA (mais recentes/por_estado/por_operador)
opa_search_well_permits	Busca de permissões com escopo estadual por condado/operador/data com limite de frescor medido
opa_lookup_well	Consulta por número de API com ciclo de vida promovido e produção mensal exata quando disponível
opa_get_well_activity	Contagens recentes de permissões/principais operadores/tendências com avisos explícitos de saúde do estado
opa_get_well_production	Produção de poços nos EUA — cobertura beta (resumo/estados/estado/poço/principais_produtores/tempo_de_ciclo/coortes)
opa_get_spread	Spreads de refino/comercialização (crack, basis, margem)

Ferramentas de Alertas de Preço (autenticadas)

Estas ferramentas criam e gerenciam alertas de preço persistentes vinculados à sua conta OilPriceAPI, portanto exigem uma chave de API (OILPRICEAPI_KEY). O mecanismo de alertas avalia atualizações de fontes elegíveis e notifica você (por e-mail, além de webhook se você fornecer um) quando uma condição é atendida.

Ferramenta	Descrição
opa_create_price_alert	Criar um alerta persistente (commodity, operador, limite, webhook opcional)
opa_list_price_alerts	Listar todos os alertas na conta
opa_delete_price_alert	Excluir permanentemente um alerta por id
opa_get_alert_triggers	Atividade recente de disparo de alertas (opcionalmente filtrada por since)

Ferramentas de Resumo de Mercado e Assinaturas (autenticadas)

O resumo de mercado fornece um instantâneo de múltiplas commodities em uma única chamada. Assinaturas ("vigias") são instantâneos persistentes e recorrentes vinculados à sua conta — a API registra um evento a cada intervalo, e o agente consulta novos eventos por meio de um cursor por usuário (os eventos são consultados, não enviados — não há conexão sempre ativa). Estas exigem uma chave de API (OILPRICEAPI_KEY). Uma assinatura difere de um alerta: uma vigia sempre emite um evento a cada intervalo (um registro contínuo), enquanto um alerta dispara apenas em uma travessia de limite. Limites por conta de código, vigia e cadência se aplicam; a resposta da API é autoritativa e retorna o limite atual quando excedido.

Ferramenta	Descrição
opa_get_market_brief	Resumo de múltiplas commodities: preços, variações de 24h, previsões de 1m, spreads, narrativa opcional
opa_create_price_subscription	Criar uma vigia recorrente persistente (códigos, intervalo como 5m/1h/daily)
opa_list_subscriptions	Listar todas as assinaturas na conta
opa_delete_subscription	Excluir permanentemente uma assinatura por id
opa_get_subscription_events	Consultar novos eventos de vigia desde um cursor (since); retorna instantâneos + deltas

Perguntas de Exemplo

"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

Dados de preço assináveis (JSON):

Recurso	URI	Descrição
Fatos do Produto	oilpriceapi://product-facts	Contrato de produto público revisado e versionado
Brent Crude	price://brent	Preço global do petróleo bruto de referência
WTI Crude	price://wti	Preço do petróleo bruto de referência dos EUA
Gás Natural	price://natural-gas	Preço do gás natural Henry Hub dos EUA
Diesel	price://diesel	Preço médio nacional de diesel dos EUA
Visão de Mercado	price://all	Preços atuais visíveis na conta da API

Fatos do Produto e Conhecimento do Modelo

opa_get_product_facts e oilpriceapi://product-facts melhoram a precisão para uma sessão MCP conectada. Eles não retreinam um modelo nem atualizam seu conhecimento geral. O servidor prefere o contrato canônico sem chave, usa um cache limitado e rotula qualquer pacote de fallback verificado por soma de verificação com metadados de origem e aviso.

Prompts

Modelos de analista pré-construídos:

Prompt	Descrição
daily-briefing	Briefing diário do mercado de energia com preços-chave e movimentadores
brent-wti-spread	Analisar o spread do petróleo bruto Brent-WTI
gas-market-analysis	Comparar os mercados de gás natural dos EUA vs europeus
commodity-report	Relatório detalhado sobre uma commodity específica (parametrizado)
diesel-cost-analysis	Comparar preços de diesel entre estados dos EUA para planejamento de frota
supply-analysis	Analisar a oferta usando produção da OPEP, contagens de sondas, armazenamento

Suporte a Linguagem Natural

Você diz	Nós entendemos
"óleo brent", "petróleo brent"	BRENT_CRUDE_USD
"wti", "óleo dos EUA"	WTI_USD
"gás natural", "henry hub"	NATURAL_GAS_USD
"gás europeu", "ttf"	DUTCH_TTF_EUR
"diesel"	DIESEL_USD
"ouro"	GOLD_USD
"combustível de aviação", "querosene de aviação"	JET_FUEL_USD
"carbono", "créditos de carbono"	EU_CARBON_EUR

Desenvolvimento

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

Mudanças de Quebra na v3.0.0

• O escopo padrão das ferramentas agora é somente leitura. Ferramentas de criar/excluir alertas e assinaturas exigem --scope write ou OILPRICEAPI_MCP_SCOPE=write explícitos.
• Configuração inválida de escopo/perfil/categoria agora falha antes do início do stdio do MCP.
• Use --list-tools --json ou --capabilities --json em vez de depender de um inventário codificado.

Mudanças de Quebra na v2.0.0

• Todos os nomes de ferramentas agora usam o prefixo opa_ (por exemplo, get_commodity_price -> opa_get_price)
• Nomes de commodities não reconhecidos agora retornam um erro com sugestões em vez de assumir silenciosamente Brent
• list_commodities agora busca ao vivo da API (recorre à lista estática se indisponível)

A caixa de ferramentas completa do OilPriceAPI

Mesmos dados, em todas as pilhas:

Ferramenta	Instalação
SDK Python	pip install oilpriceapi
SDK Node/TypeScript	npm install oilpriceapi
SDK PHP	composer require oilpriceapi/oilpriceapi
SDK Go	go get github.com/OilpriceAPI/oilpriceapi-go
Plugin WordPress	widgets de preço sem código

Explore a API

• 🧭 Explorador interativo: api.oilpriceapi.com/swagger — experimente cada endpoint no navegador (modo demo, sem chave necessária)
• 📜 Especificação OpenAPI: swagger.json

Política de Privacidade

Este servidor MCP roda localmente na sua máquina e só se comunica com o serviço OilPriceAPI:

• O que é enviado: solicitações de ferramentas são traduzidas em chamadas HTTPS para api.oilpriceapi.com (códigos de commodities, parâmetros de consulta como período de tempo ou estado, slugs de transportadoras e entradas de nível de serviço para sobretaxas de combustível, e — para ferramentas de alerta/assinatura — os parâmetros de alerta que você especificar), autenticadas com sua chave de API. Nenhum conteúdo de conversa é transmitido — apenas as entradas estruturadas de ferramentas acima.
• Armazenamento da chave de API: sua chave é armazenada localmente na configuração do seu cliente MCP (ou na variável de ambiente OILPRICEAPI_KEY). Ela é enviada apenas para api.oilpriceapi.com como um cabeçalho Authorization.
• Registro e telemetria de demanda: cada ferramenta emite um evento local estruturado de acerto/erro para stderr e atribui sua solicitação de API com o nome da ferramenta mais uma forma de argumento deliberadamente perda. Códigos de commodities, intervalos, códigos de estado e controles numéricos limitados podem ser retidos; texto livre, prompts, nomes, IDs, números de poços da API, coordenadas e limites são reduzidos a provided. O registro de solicitações de API segue a Política de Privacidade do OilPriceAPI.
• Terceiros: nenhum dado é compartilhado com terceiros além do que essa política descreve.
• Modo demo: sem uma chave de API, as ferramentas de preço chamam o endpoint demo sem chave no mesmo host; nenhuma chave ou dado de conta está envolvido.

Perguntas: support@oilpriceapi.com

Limite de Preço (HTTP 402)

Onde a linha gratuita/paga fica para este servidor (#10):

• Sempre aberto: o próprio servidor MCP (MIT), configuração, documentação, descoberta (listagem de ferramentas) e modo demo sem chave para avaliação de baixo volume.
• Chave de API: use os fatos públicos do produto e a resposta da sua conta para o teste atual, cota, janela de redefinição e direito ao conjunto de dados. O modo demo sem chave permanece disponível para um conjunto de dados limitado.
• Atrás do paywall: uso de alto volume e conjuntos de dados premium (futuros, inteligência de energia, permissões/produção de poços, alertas em escala). Quando uma solicitação cruza esse limite, a API retorna um HTTP 402/403/429 padrão com o limite exato ou bloqueio de recurso no corpo, e este servidor exibe essa mensagem mais um link de atualização — os agentes recebem uma parada legível por máquina, nunca uma falha silenciosa.
• Protocolo x402: micropagamentos criptográficos por solicitação via protocolo x402 não são suportados atualmente — o pagamento é feito pelo plano da conta (Stripe), autenticado com sua chave de API.

Licença

MIT

Links

• OilPriceAPI
• Documentação da API
• Preços
• Protocolo MCP

Também Disponível Como

• SDK Python - Cliente Python com integração Pandas
• SDK Node.js - SDK TypeScript/JavaScript
• SDK Go - Cliente Go idiomático
• Integração OpenBB - Provedor da plataforma OpenBB