> ## Documentation Index
> Fetch the complete documentation index at: https://www.worldmonitor.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP 工具：贸易、关税与价格

> World Monitor MCP 工具参考：贸易流、关税、进口关税、消费价格、粮食库存与采购。逐一列出每个工具的输入参数与类型、数据新鲜度窗口、对应的后端 REST API 端点，以及可直接复制使用的示例调用负载，帮助开发者构建情报智能体、工作流自动化与自定义 MCP 客户端集成。

本页属于 [MCP 工具参考](https://www.worldmonitor.app/docs/zh/mcp-tools-reference.md)，该索引列出全部工具。连接、认证、套餐与错误见 [MCP Server 概览](https://www.worldmonitor.app/docs/zh/mcp-overview.md)。

以下工具暂仅提供英文参考：[`get_food_stocks`](https://www.worldmonitor.app/docs/mcp-tools/trade#get_food_stocks)。

`curl` 示例假设已执行 `export WM_KEY="wm_…"`；使用 OAuth 时，请将 `-H "X-WorldMonitor-Key: $WM_KEY"` 替换为 `-H "Authorization: Bearer $TOKEN"`。

### `get_wto_trade_flows`

查询一个报告国与世界之间、可配置年份窗口内的 WTO 商品贸易流量。数据来自 WTO `ITS_MTV_AX`（出口）和 `ITS_MTV_AM`（进口）指标，每 6 小时播种一次；该工具读取与仪表板相同的播种快照，不会在每次请求时调用 WTO。

**参数（工具特定）：**

| 名称 | 类型 | 描述 |
| - | - | - |
| `reporter` | string | 报告国的 ISO 3166-1 alpha-2 代码（"US"）或 3 位 UN M49 代码（"840"）；ISO2 会映射为 M49。默认为 "840"（美国）。目前仅提供与世界（"000"）之间的数据；其他伙伴代码会返回 `not_covered`。 |
| `years` | integer | 从最新发布年份向前回看的年数，包含起止年份（10 会返回 11 个日历年）。默认为 10；30 是完整播种窗口。 |

**响应区分：** `unavailableReason` 使用 RPC 的封闭 `TradeFlowUnavailableReason` 枚举。`TRADE_FLOW_UNAVAILABLE_REASON_NOT_COVERED` 是合约答案：该组合不在播种覆盖范围内，重试无效。其他非 UNSPECIFIED 原因均表示故障（`seed_missing`、`coverage_unknown`、`cache_unavailable`），并带有 `upstreamUnavailable: true`。

* **API 端点：** `GET /api/trade/v1/get-trade-flows`
* **类型：** 规范贸易流量路由的 RPC 代理（handler 负责窗口切片和未命中分类）。
* **新鲜度预算：** 最多 **7 小时**后标记为 `stale`（6 小时播种节奏加 1 小时宽限）。

```bash curl theme={null}
curl -s https://worldmonitor.app/mcp \
  -H "X-WorldMonitor-Key: $WM_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0","id":1,
    "method":"tools/call",
    "params":{"name":"get_wto_trade_flows","arguments":{"reporter":"840","years":20}}
  }'
```

### `get_tariff_averages`

一个国家按年份适用的平均关税：截至 2023 年的税则税率，不含 301/232 条款关税。不传伙伴和产品组时，返回任一报告国的 WTO 全部产品 MFN 平均税率（`TP_A_0010`），包括美国（`840`）。传入非“世界”的伙伴或产品组时，返回来自 UNCTAD TRAINS（经 World Bank WITS）的实际适用平均税率：

* `tariffRate` 为简单平均（`AHS-SMPL-AVRG`），计入该伙伴可享受的优惠。
* `weightedRate` 为进口加权平均（`AHS-WGHTD-AVRG`）。

多数报告国的序列约从 1990 年至 2023 年。美国的优惠税率仅报告到 2021 年。这些是税则税率：不包含 301 条款、232 条款及其他单边关税。美国请使用 `get_us_import_duty`。

**参数（工具特定）：**

| 名称 | 类型 | 描述 |
| - | - | - |
| `reporter` | string | 进口国。默认为美国（`840`）。3 位 UN M49 代码原样传递，因此 WTO 代码（`699` 印度）和欧盟（`918` 或 `"EU"`）均可用。也接受 ISO alpha-2、alpha-3 和英文名称；法国、挪威、印度和瑞士会以其 WTO 代码（`251`、`579`、`699`、`757`）发送，MFN 序列以这些代码为键。 |
| `partner` | string | 被计算平均税率的出口国。省略或传 `"World"`（`000`）表示所有伙伴。该数据集中欧盟不能作为伙伴。 |
| `product_group` | string（枚举） | WITS 产品组：HS 章节范围如 `84-85_MachElec`、`50-63_TextCloth`，或汇总组如 `Textiles`、`Food`、`Fuels`、`manuf`。`all` 或省略表示全部产品。 |
| `years` | integer | 返回的年数，保留最新年份（0–30）。0 或省略表示路由默认值（10）。 |

**响应区分：** 每个数据点的 `indicatorCode`、`partnerCountry` 和 `productSector` 说明由哪个序列作答。`TARIFF_TREND_UNAVAILABLE_REASON_NOT_COVERED` 是覆盖范围答案（WITS 没有该序列）。`TARIFF_TREND_UNAVAILABLE_REASON_UPSTREAM_UNAVAILABLE` 是故障，并带有 `upstreamUnavailable: true`；请稍后重试。

**覆盖范围：** 除上游故障外，每个答案都带有一个由 MCP 服务器添加的 `coverage` 对象。上游故障（`upstreamUnavailable: true`）不提供任何答案，因此不带该对象。`dataset` 表示所查询的数据集；信任税率之前，请先检查 `unavailableReason`。它在未传入非“世界”伙伴且未传入产品组时为 `WTO_MFN`，否则为 `WITS_TRAINS`。`rateBasis` 为 `SCHEDULE`，`includesUnilateralDuties` 为 `false`，`excludedDutyTypes` 列出 `SECTION_301`、`SECTION_232`、`IEEPA`、`ANTI_DUMPING` 和 `COUNTERVAILING`。`latestYear` 取 `coverageEndYear`，没有时取最新数据点的年份，没有任何年份作答时不出现。报告国为美国时，`seeAlso` 指向 `get_us_import_duty` 并说明原因。

* **API 端点：** `GET /api/trade/v1/get-tariff-trends`
* **访问：** `subscription` — 需要 Pro 订阅。RPC 工具：无 `summary` 参数（使用 `jmespath` 精简响应）。
* **类型：** 规范路由的 RPC 代理。伙伴和产品组序列在缓存未命中时从 WITS 读取，并缓存 7 天。

```bash curl theme={null}
curl -s https://worldmonitor.app/mcp \
  -H "X-WorldMonitor-Key: $WM_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0","id":1,
    "method":"tools/call",
    "params":{"name":"get_tariff_averages","arguments":{"reporter":"US","partner":"China","product_group":"Textiles","years":5}}
  }'
```

### `get_bilateral_tariff`

两国之间某一 HS6 产品的关税：截至 2023 年的税则税率，不含 301/232 条款关税。即一个国家在某一年对来自某一伙伴的某个 6 位 HS 产品适用的关税，来自 UNCTAD TRAINS（经 World Bank WITS）。`appliedRate` 是该伙伴实际支付的税率：其可享受的最优优惠税率，否则为 MFN。`basis` 说明是哪一种。`mfnRate`、`preferentialRate` 和按协定列出的 `groupPreferences` 分别报告。MFN 为从量税时，`mfnAveRate` 给出从价等值。欧盟成员国按欧盟税则作答（`filingReporter` 为 `918`）。

仅为税则税率：不包含 301 条款、232 条款、反倾销及其他单边关税。TRAINS 没有 2021 年以后的美国优惠数据，也没有 2023 年以后的美国数据，因此美国请使用 `get_us_import_duty`。

**参数（工具特定）：**

| 名称 | 类型 | 描述 |
| - | - | - |
| `reporter` | string | 进口国（必填）。3 位代码、ISO alpha-2 或 alpha-3，或英文名称。 |
| `partner` | string | 出口国（必填）。格式同上。 |
| `hs_code` | string | 6 位 HS 编码（必填），如 `870380`。点号会被忽略。 |
| `year` | integer | 关税年份。0 或省略表示有数据的最新年份。 |

**响应区分：** `BILATERAL_TARIFF_UNAVAILABLE_REASON_NOT_COVERED` 是覆盖范围答案。`BILATERAL_TARIFF_UNAVAILABLE_REASON_UPSTREAM_UNAVAILABLE` 是故障，并带有 `upstreamUnavailable: true`。

**覆盖范围：** 除上游故障外，每个答案都带有一个由 MCP 服务器添加的 `coverage` 对象。上游故障（`upstreamUnavailable: true`）不提供任何答案，因此不带该对象。`dataset` 表示所查询的数据集；信任税率之前，请先检查 `unavailableReason`。它始终为 `WITS_TRAINS`。`rateBasis` 为 `SCHEDULE`，`includesUnilateralDuties` 为 `false`，`excludedDutyTypes` 列出 `SECTION_301`、`SECTION_232`、`IEEPA`、`ANTI_DUMPING` 和 `COUNTERVAILING`。`latestYear` 为作答的年份，`NOT_COVERED` 答案中不出现。报告国为美国时，`seeAlso` 指向 `get_us_import_duty` 并说明原因。

* **API 端点：** `GET /api/trade/v1/get-bilateral-tariff`
* **访问：** `subscription` — 需要 Pro 订阅。RPC 工具：无 `summary` 参数（使用 `jmespath` 精简响应）。
* **类型：** 规范路由的 RPC 代理，缓存未命中时读取 WITS。冷读取可能需要数秒。

```bash curl theme={null}
curl -s https://worldmonitor.app/mcp \
  -H "X-WorldMonitor-Key: $WM_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0","id":1,
    "method":"tools/call",
    "params":{"name":"get_bilateral_tariff","arguments":{"reporter":"India","partner":"US","hs_code":"870380"}}
  }'
```

### `get_us_import_duty`

美国当前对来自某国的某一产品征收的关税：实时 HTS 税率，加上现行有效的 301 条款和 232 条款关税（如适用）。对 `hs_code` 下的每个 8 位税目，返回 USITC 协调关税表（HTS）的实时税率和 `basis`（`MFN`、带 `preferenceProgram` 的 `PREFERENTIAL`，或 `COLUMN_2`）。同时返回现行有效的第 99 章 301 条款和 232 条款关税，每项带有 `status`：

* `APPLIES`
* `CONDITIONAL`，并以 `condition` 说明取决于什么
* `EXEMPT`
* `SCHEDULED`

`estimatedRate` 只把 `APPLIES` 关税加到基础税率上。当从量税、条件或未解析的优惠项目使结果不确定时，`estimateComplete` 为 false。IEEPA 关税已停止征收，不予报告。不包含反倾销税和反补贴税。`additionalDutiesLoaded: false` 表示只有基础税率可用。

**参数（工具特定）：**

| 名称 | 类型 | 描述 |
| - | - | - |
| `hs_code` | string | 6、8 或 10 位 HTS 编码（必填），如 `870380` 或 `8703.80.00`。点号会被忽略。 |
| `partner` | string | 原产国（必填）。3 位代码、ISO alpha-2 或 alpha-3，或英文名称。 |

**覆盖范围：** 除上游故障外，每个答案都带有一个由 MCP 服务器添加的 `coverage` 对象。上游故障（`upstreamUnavailable: true`）不提供任何答案，因此不带该对象。`dataset` 表示所查询的数据集；信任税率之前，请先检查 `unavailableReason`。它为 `USITC_HTS`，`rateBasis` 为 `CURRENT_DUTY`。只有 `additionalDutiesLoaded` 为 `true` 时，`includesUnilateralDuties` 才为 `true`，此时 `excludedDutyTypes` 列出 `IEEPA`、`ANTI_DUMPING` 和 `COUNTERVAILING`。否则答案仅含基础税率：`includesUnilateralDuties` 为 `false`，`excludedDutyTypes` 还会列出 `SECTION_301` 和 `SECTION_232`。`asOf` 为作答的 HTS 版本。

* **API 端点：** `GET /api/trade/v1/get-us-import-duty`
* **访问：** `subscription` — 需要 Pro 订阅。RPC 工具：无 `summary` 参数（使用 `jmespath` 精简响应）。
* **类型：** 规范路由的 RPC 代理：实时读取 HTS 税目，并与播种的第 99 章目录（`trade:us-hts:catalog:v1`）合并。

```bash curl theme={null}
curl -s https://worldmonitor.app/mcp \
  -H "X-WorldMonitor-Key: $WM_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0","id":1,
    "method":"tools/call",
    "params":{"name":"get_us_import_duty","arguments":{"hs_code":"870380","partner":"CN"}}
  }'
```

### `get_consumer_prices`

逐国消费价格情报：30 天概览、类别级通胀、零售商价差（必需品篮子）、涨跌榜和来源新鲜度。需要 country\_code（当前仅播种 'ae'）。

**参数：**

| 名称 | 类型 | 必填 | 描述 |
| - | - | -: | - |
| `country_code` | string | **是** | ISO 3166-1 alpha-2 国家代码。当前支持：AE（不区分大小写）。 |

* **API 端点：** `GET /api/consumer-prices/v1/get-consumer-price-freshness`, `GET /api/consumer-prices/v1/get-consumer-price-overview`, `GET /api/consumer-prices/v1/list-consumer-price-categories`, `GET /api/consumer-prices/v1/list-consumer-price-movers`, `GET /api/consumer-prices/v1/list-retailer-price-spreads`
* **类型：** 混合 — 直接读取缓存键（亚秒级），但需要输入参数来选择切片。
* **新鲜度预算：** 每个切片最多 **25 小时**（24 小时 cron + 1 小时宽限）后标记 `stale: true`。

```bash curl theme={null}
curl -s https://worldmonitor.app/mcp \
  -H "X-WorldMonitor-Key: $WM_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0","id":1,
    "method":"tools/call",
    "params":{"name":"get_consumer_prices","arguments":{"country_code":"AE"}}
  }'
```

### `get_procurement_opportunities`

通过规范的、仅限 Pro 的招标 API 搜索活跃的全球公共采购机会。此工具绝不直接读取 Upstash。它返回规范记录的紧凑投影：官方公告 URL、来源、标题、买方、时间、金额、分类、领域、`participationMode` 与精简的 `automationFit`；有意省略描述、资格要求和提交 URL。

**参数（工具特定）：**

| 名称 | 类型 | 描述 |
| - | - | - |
| `country` | string | 一个 ISO 3166-1 alpha-2 国家代码。 |
| `countries` | `array<string>` | 额外国家代码；与 `country` 合并。 |
| `source` | string | 官方来源适配器，例如 `sam`、`ted`、`contracts-finder`、`canada-buys`、`gets` 或 `world-bank`。 |
| `query` | string | 对标题和描述进行不区分大小写的文本搜索。 |
| `buyer` | string | 不区分大小写的买方或采购机构文本。 |
| `deadline_from` / `deadline_to` | string | ISO-8601 的包含式截止日期范围。 |
| `sort` | `string: newest / closing_soon / estimated_value / relevance` | 排序方式；默认为 `newest`。 |
| `min_automation_score` | integer | 可选关键词相关性评分阈值。正整数会传给规范路由（大于 100 时由其截断）；非整数和非正值会被忽略。该筛选为可选，**不是**投标资格证据。 |
| `page_size` | integer | 默认 **10** 条，最多 **25** 条。这是 MCP 输出预算；REST 路由本身最多允许 100 条。 |
| `cursor` | string | 上一页结果的非透明 `nextCursor`；翻页时保持相同筛选和排序。 |

* **API 端点：** `GET /api/economic/v1/list-global-tenders`
* **类型：** 受预算约束的规范路由代理——Pro 权益仍由下游路由强制执行；不暴露 bootstrap 或直接缓存读取。
* **输出预算：** 默认 10 条紧凑记录，最多 25 条。结果保留 `nextCursor`、`total`、`appliedFilters`、`countryCoverage`、`availability`、快照时间和各来源健康摘要。空字符串 `nextCursor` 表示没有更多页面。

无筛选调用保持标准的所有开放机会行为；绝不会隐式启用 `min_automation_score`。`automationFit` 仅是关键词相关性证据，绝不是代理或供应商可否投标的法律判断。`participationMode: "unknown"` 的含义不变——上游并未确定参与方式。

```bash curl theme={null}
curl -s https://worldmonitor.app/mcp \
  -H "X-WorldMonitor-Key: $WM_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0","id":1,
    "method":"tools/call",
    "params":{"name":"get_procurement_opportunities","arguments":{"country":"US","min_automation_score":70,"page_size":10,"sort":"relevance"}}
  }'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.