Jodi

@pipeworx/jodi

按国家统计的月度石油和天然气产量、消费量、进出口量及期末库存——JODI-Oil 和 JODI-Gas 世界数据库，由各国向联合组织数据倡议（APEC/Eurostat/GECF/IEA/IEF/OLADE/OPEC/UNSD）自行报告。覆盖全球（约 100 多个国家），包括所有海湾产油国（沙特阿拉伯、阿联酋、科威特、卡塔尔、阿曼、巴林、伊拉克、伊朗）。

这是 Pipeworx 的一部分——一个将 AI Agent 连接到 1882 多个实时数据源的 MCP 网关。这是一个独立的非官方集成，与上游提供方没有隶属关系、未获其认可，也非由其发布。

工具

• jodi_oil_series(country, product?, flow?, months?, end_month?) — 某个国家的月度石油序列（原油/NGL/其他/原油合计，或某种精炼产品），并明确标记报告缺口。
• jodi_gas_series(country, flow?, months?, end_month?) — 天然气数据的对应工具（产量、按 LNG 与管道拆分的进出口量、需求、库存）。
• jodi_oil_compare(countries?, product?, flow?, months_back?, end_month?) — 按某个序列的变化幅度排列各国排名，比较最新报告月份与 N 个月前的数据。默认使用海湾产油国集合。既可回答“本季度哪些海湾产油国增产最多”（months_back: 3），也可回答“沙特出口量与一年前相比如何”（countries: ["Saudi Arabia"], months_back: 12）——比较方式相同，只需使用不同的国家列表。
• jodi_gas_compare(countries?, flow?, months_back?, end_month?) — 天然气数据的对应工具。
• jodi_countries(commodity?) — 查询 JODI-Oil/Gas 覆盖的国家，以及各国最早和最新的报告月份。

认证

无需密钥。无需提供上游密钥。

数据来源

• https://www.jodidata.org/oil/database/data-downloads.aspx — JODI-Oil 年度 CSV 文件（主要数据：原油/NGL/其他/原油合计；次要数据：精炼产品），每年一个文件，涵盖 2002 年至今。
• https://www.jodidata.org/gas/database/data-downloads.aspx — JODI-Gas，一个 CSV 文件涵盖其 2009 年至今的完整历史数据，通过 JODI 自有的 https://api.publisher.jodidata.org/web/files/gas JSON API 获取，而非使用硬编码文件名（该文件此前已改名过一次）。

由 workers/data-pipeline/src/datasets/jodi.ts 每月摄取到 jodi_oil_observations / jodi_gas_observations（迁移 161）。完整设计说明——为何未报告的数据应表示为缺失行，而不是存储为 null；以及为何摄取时 JODI 发布的五种单位中每种流量只保留一种——请参阅迁移文件和数据集配置。简要说明如下：

• 缺失月份绝不等于零。 JODI 的数据由各国自行报告，覆盖并不均衡——有些国家报告较晚，有些会跳过某些月份，还有些从不报告特定序列。此处的每个工具都会构建完整的预期月份范围，并将缺口标记为 {reported: false, value: null}，而不是只返回已存在的行，让缺口看起来像是没有数据。
• 单位预先选定，用户无法自行选择。 JODI 以 5 种单位发布每个数值；此数据包对石油流量数据采用 KBD（千桶/日），对两种水平流量（期末库存、库存变化）采用 KBBL（千桶；JODI 本身将这两种流量的 KBD 标为“不适用”），对所有天然气数据采用 M3（百万立方米）。
• 国家名称使用 ISO 3166-1 alpha-2 代码；JODI 原始文件只包含代码，因此此数据包在 src/index.ts 的 COUNTRY_NAMES 中维护了自己的代码→名称映射表，涵盖两个数据库中出现的所有代码。

快速开始

添加到你的 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）：

{
  "mcpServers": {
    "jodi": {
      "url": "https://gateway.pipeworx.io/jodi/mcp"
    }
  }
}

此端点实际提供的内容

https://gateway.pipeworx.io/jodi/mcp 上的 tools/list 会返回上表中的工具，以及 Pipeworx 共享元工具——ask_pipeworx、 discover_tools、search_within、remember/recall 和网关范围内的其他工具。因此，你看到的工具数量会多于此表：目前，单个工具包端点除了列出该工具包自有的工具，还会列出大约 30 个共享工具。连接的 initialize 响应会说明其确切范围，是当天有效范围的权威说明。

这是有意设计的，并非意外进行了多路复用。元工具能让限定范围的连接回答此工具包未涵盖的问题——通过 ask_pipeworx 跨整个目录进行路由——无需再添加第二个 MCP 服务。目前无法挂载不含这些工具的工具包端点；如果额外的架构定义占用的上下文比路由带来的价值更大，请连接一次完整网关，而不是连接多个工具包端点。

或者连接完整的 Pipeworx 网关，直接列出每个工具包的工具，而不仅仅是此工具包的工具：

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

两个 URL 都连接到同一个网关和相同的 1882+ 个数据源。唯一的区别在于哪些工具包的工具会被直接列出；无论连接哪个端点，ask_pipeworx 都能访问所有工具。

没有 MCP 客户端？通过 HTTP 调用

curl -X POST https://gateway.pipeworx.io/v1/tools/jodi_oil_series \
  -H 'Content-Type: application/json' \
  -d '{"country":"Saudi Arabia","flow":"exports","months":24}'

首次调用无需账户。检查任意工具：GET https://gateway.pipeworx.io/v1/tools/jodi_oil_series。查找工具：使用 {"query":"..."} 调用 POST https://gateway.pipeworx.io/v1/tools/search_packs。

独立运行（无需网关账户）

此软件包也可以作为本地 stdio MCP 服务运行——无需 Pipeworx 账户，也无需往返网关：

{
  "mcpServers": {
    "jodi": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-jodi"]
    }
  }
}

或者直接运行它，确认服务能够启动：

npx -y @pipeworx/mcp-jodi

它通过 stdin/stdout 使用 MCP 通信，并仅针对此工具包的工具响应 initialize/tools/list/tools/call——不包含上文网关连接额外提供的任何共享元工具。来源相同，工具相同，但没有 ask_pipeworx 路由。

使用 ask_pipeworx

你可以用通俗的英语提问，而不必直接调用工具——这既适用于上面的工具包端点，也适用于完整网关：

ask_pipeworx({ question: "your question about Jodi data" })

网关会选择合适的工具并自动填写参数。

更多信息

• 文档和指南
• pipeworx.io

许可证

MIT