imf-data

# IMF Data（全球宏观经济数据分析）

## 功能概述

通过 **IMF Data MCP Server** 直接查询国际货币基金组织的官方宏观经济数据，覆盖 190 个成员国：

1. **实体经济指标**：GDP、CPI、汇率、利率、货币供应量（IFS）
2. **国际收支**：经常账户、资本账户、金融账户（BOP）
3. **双边贸易**：进出口数据、贸易方向统计（DOT）
4. **跨境投资**：直接投资头寸（CDIS）、证券投资头寸（CPIS）
5. **财政数据**：政府收支、公共债务（GFS）
6. **货币金融**：央行/商业银行资产负债表（MFS）
7. **金融稳健性**：银行资本充足率、不良贷款率（FSI）

**核心价值**：无需 API Key，免费访问全球最权威的宏观经济数据体系。

---

## 使用时机

当用户需要以下内容时使用此技能：

- **经济指标查询**：「中国 2020-2025 年的 GDP 增长率」「美国最新 CPI 数据」
- **多国对比**：「比较 G7 国家的通胀率」「金砖国家 GDP 对比」
- **贸易分析**：「中美双边贸易数据」「中国对东盟的出口趋势」
- **风险评估**：「土耳其的银行不良贷款率」「阿根廷国际收支状况」
- **货币政策**：「各国央行政策利率对比」「中国 M2 货币供应趋势」
- **投资宏观研判**：为个股/行业分析提供宏观经济背景数据

**不要使用**：

- 个股/公司财务数据 → 使用 `us-stock-analysis` 技能
- 实时市场行情（股价、期货）→ IMF 数据为月/季/年频率
- WEO 预测数据 → 当前 MCP Server 未封装 WEO 数据集
- 最新信息检索 → 使用 `web-research` 技能

---

## 可用工具

### 数据查询工具（8 个数据集）

| 工具 | 数据集 | 核心内容 | 频率 | 何时使用 |
|------|--------|----------|------|----------|
| `fetch_ifs_data` | IFS 国际金融统计 | GDP、CPI、汇率、利率、M2 | 月/季 | **最常用**，查询核心经济指标 |
| `fetch_bop_data` | BOP 国际收支 | 经常/资本/金融账户 | 季/年 | 分析资本流动、经常账户 |
| `fetch_dot_data` | DOT 贸易方向 | 双边进出口数据 | 月/季 | 分析双边贸易、贸易依赖度 |
| `fetch_fsi_data` | FSI 金融稳健性 | 银行资本率、不良贷款率 | 季度 | 评估国家金融系统健康度 |
| `fetch_gfsmab_data` | GFS 政府财政 | 政府收支、债务 | 年度 | 分析财政赤字、公共债务 |
| `fetch_mfs_data` | MFS 货币金融 | 央行/商行资产负债表 | 月度 | 分析货币供应、信贷增长 |
| `fetch_cdis_data` | CDIS 直接投资 | 跨境 FDI 头寸 | 年度 | 分析外商直接投资 |
| `fetch_cpis_data` | CPIS 证券投资 | 跨境证券投资头寸 | 半年 | 分析跨境证券投资流动 |

### 辅助工具（2 个）

| 工具 | 用途 | 何时使用 |
|------|------|----------|
| `list_indicators` | 列举指定数据集的所有可用指标代码 | 不确定指标代码时先查询 |
| `list_countries` | 列举指定数据集的所有可用国家代码 | 不确定国家代码时先查询 |

---

## 执行流程（必须遵循）

### 第 1 步：需求分析与数据集选择

分析用户问题，确定所需的：

- **分析对象**：哪些国家/地区？
- **分析指标**：GDP？CPI？贸易？金融稳健性？
- **时间范围**：起止年份？
- **分析深度**：单一指标查询？多维交叉分析？

**数据集选择矩阵**：

| 用户需求 | 首选数据集 | 辅助数据集 |
|----------|-----------|-----------|
| GDP、CPI、汇率、利率 | **IFS** | - |
| 国际收支、资本流动 | **BOP** | IFS（汇率） |
| 双边贸易、进出口 | **DOT** | BOP（经常账户） |
| 政府债务、财政赤字 | **GFS** | IFS（GDP 做分母） |
| 银行健康度、金融风险 | **FSI** | MFS（货币供应） |
| 跨境直接投资 (FDI) | **CDIS** | BOP（金融账户） |
| 跨境证券投资 | **CPIS** | BOP（金融账户） |
| 全面国家风险评估 | **FSI + BOP + GFS** | IFS（基础指标） |

### 第 2 步：查询参数构建

**所有工具的通用参数**：

| 参数 | 说明 | 示例 |
|------|------|------|
| `freq` | 频率：`A`=年度, `Q`=季度, `M`=月度 | `"A"` |
| `country` | 国家代码，多国用 `+` 连接 | `"CN+US+JP"` |
| `indicator` | 指标代码（从速查表或 `list_indicators` 获取） | `"NGDP_XDC"` |
| `start` | 起始年份 | `2020` |
| `end` | 结束年份 | `2025` |

**特殊参数**（部分工具独有）：

| 工具 | 额外参数 | 说明 |
|------|----------|------|
| `fetch_dot_data` | `counterpart` | 贸易对手国代码 |
| `fetch_cdis_data` | `counterpart` | 投资对手国代码 |
| `fetch_cpis_data` | `counter_country` | 投资对手国代码 |
| `fetch_gfsmab_data` | `unit` | `XDC`=本币绝对值, `XDC_R_B1GQ`=GDP 占比 |

### 第 3 步：使用速查表定位代码

> ⚠️ **先查速查表，找不到再调用 `list_indicators` / `list_countries`**

#### 常用国家代码

| 分组 | 国家 | 代码 |
|------|------|------|
| **G7** | 美国 / 日本 / 德国 / 英国 / 法国 / 意大利 / 加拿大 | `US` / `JP` / `DE` / `GB` / `FR` / `IT` / `CA` |
| **金砖** | 中国 / 印度 / 巴西 / 俄罗斯 / 南非 | `CN` / `IN` / `BR` / `RU` / `ZA` |
| **东盟核心** | 印尼 / 泰国 / 越南 / 马来西亚 / 菲律宾 / 新加坡 | `ID` / `TH` / `VN` / `MY` / `PH` / `SG` |
| **其他重要** | 韩国 / 澳大利亚 / 墨西哥 / 土耳其 / 沙特 / 阿根廷 | `KR` / `AU` / `MX` / `TR` / `SA` / `AR` |
| **特殊** | 欧元区 / 世界 | `U2` / `W00` |

#### IFS 常用指标代码

| 指标 | 代码 | 频率 | 说明 |
|------|------|------|------|
| 名义 GDP (本币) | `NGDP_XDC` | 季 | 本币计价的名义 GDP |
| 实际 GDP 指数 | `NGDP_R_K_IX` | 季 | 实际 GDP 增长指数 |
| CPI 指数 | `PCPI_IX` | 月 | 消费者价格指数 |
| 政策利率 | `FPOLM_PA` | 月 | 央行政策利率 |
| USD 汇率 | `ENDA_XDC_USD_RATE` | 月 | 本币/美元汇率 |
| 货币供应 M2 | `FMB_XDC` | 月 | 广义货币供应量 |
| 外汇储备 | `RAFA_USD` | 月 | 美元计价外汇储备 |

#### DOT 贸易指标代码

| 指标 | 代码 | 说明 |
|------|------|------|
| 出口 (FOB) | `TXG_FOB_USD` | 美元计价出口 |
| 进口 (CIF) | `TMG_CIF_USD` | 美元计价进口 |

#### BOP 常用指标代码

| 指标 | 代码 | 说明 |
|------|------|------|
| 经常账户余额 | `BCA_BP6_USD` | 经常账户收支 |
| 贸易余额 | `BGS_BP6_USD` | 商品与服务贸易差额 |
| 金融账户净额 | `BF_BP6_USD` | 金融账户净流入 |

> [!TIP]
> 以上仅列出最常用的代码。如需查找其他指标，调用 `list_indicators(dataset_id="IFS")` 获取完整列表。

### 第 4 步：获取数据（支持并行）

**单指标查询**：

```
fetch_ifs_data:
  freq: "A"
  country: "CN"
  indicator: "NGDP_XDC"
  start: 2020
  end: 2025
```

**多国对比**（推荐并行调用）：

```
# 并行查询多个国家的同一指标
fetch_ifs_data:
  freq: "A"
  country: "CN+US+JP+DE+GB"
  indicator: "PCPI_IX"
  start: 2020
  end: 2025
```

**多数据集交叉分析**（并行调用不同工具）：

```
# 并行：IFS 基础指标 + BOP 国际收支 + DOT 贸易数据
fetch_ifs_data:
  freq: "A", country: "CN", indicator: "NGDP_XDC", start: 2020, end: 2025

fetch_bop_data:
  freq: "A", country: "CN", indicator: "BCA_BP6_USD", start: 2020, end: 2025

fetch_dot_data:
  freq: "A", country: "CN", indicator: "TXG_FOB_USD", counterpart: "US", start: 2020, end: 2025
```

**不确定代码时的查询模式**：

```
# 第一步：查询可用指标
list_indicators:
  dataset_id: "FSI"

# 第二步：根据返回结果选择正确的 indicator 代码
fetch_fsi_data:
  freq: "A", country: "CN", indicator: "[从上步获取的代码]", start: 2020, end: 2025
```

### 第 5 步：分析与输出

- 将返回的时间序列数据整理为**表格形式**
- 计算关键衍生指标（同比增速、占比等）
- 多国数据进行横向对比
- 附加分析洞察和趋势解读
- 标注数据来源（IMF + 具体数据集）

---

## 输出格式模板

### 模板 A：单国经济分析

```markdown
## [国家名称] 经济分析（[时间范围]）

> **数据来源**：IMF [数据集名称]
> **分析日期**：YYYY-MM-DD

### 核心经济指标

| 指标 | [年份1] | [年份2] | [年份3] | [年份4] | [年份5] | 趋势 |
|------|---------|---------|---------|---------|---------|------|
| **GDP (本币)** | X.XX | X.XX | X.XX | X.XX | X.XX | 📈/📉 |
| **CPI 通胀率** | X.X% | X.X% | X.X% | X.X% | X.X% | 📈/📉 |
| **政策利率** | X.X% | X.X% | X.X% | X.X% | X.X% | 📈/📉 |
| **USD 汇率** | X.XX | X.XX | X.XX | X.XX | X.XX | 📈/📉 |
| **外汇储备** | $X.XX B | $X.XX B | $X.XX B | $X.XX B | $X.XX B | 📈/📉 |

### 分析洞察

**宏观环境评估**：[整体经济状况分析]
**关键趋势**：[核心趋势发现]
**风险提示**：[潜在风险因素]
```

### 模板 B：多国对比分析

```markdown
## [指标名称] 多国对比（[时间范围]）

> **数据来源**：IMF [数据集名称]
> **对比国家**：[国家列表]

### 横向对比

| 国家 | [年份1] | [年份2] | [年份3] | [年份4] | [年份5] | 平均值 | 趋势 |
|------|---------|---------|---------|---------|---------|--------|------|
| 🇨🇳 中国 | X.XX | X.XX | X.XX | X.XX | X.XX | X.XX | 📈/📉 |
| 🇺🇸 美国 | X.XX | X.XX | X.XX | X.XX | X.XX | X.XX | 📈/📉 |
| 🇯🇵 日本 | X.XX | X.XX | X.XX | X.XX | X.XX | X.XX | 📈/📉 |
| 🇩🇪 德国 | X.XX | X.XX | X.XX | X.XX | X.XX | X.XX | 📈/📉 |

### Key Insights

- 🏆 **[排名/领先者]**：[数据] + [解释]
- 📈 **[趋势发现]**：[数据] + [解释]
- ⚠️ **[分歧/风险]**：[数据] + [解释]
```

### 模板 C：国家风险评估

```markdown
## [国家名称] 风险评估报告

> **数据来源**：IMF FSI / BOP / GFS / IFS
> **评估日期**：YYYY-MM-DD

### 风险评分概览

| 风险类别 | 关键指标 | 最新值 | 安全阈值 | 评级 |
|----------|----------|--------|----------|------|
| **金融风险** | 不良贷款率 | X.X% | <5% | 🟢/🟡/🔴 |
| **金融风险** | 资本充足率 | X.X% | >8% | 🟢/🟡/🔴 |
| **外部风险** | 经常账户/GDP | X.X% | >-3% | 🟢/🟡/🔴 |
| **财政风险** | 公共债务/GDP | X.X% | <60% | 🟢/🟡/🔴 |
| **通胀风险** | CPI 年化 | X.X% | <5% | 🟢/🟡/🔴 |

### 综合评级

**整体风险水平**：[低/中/高/极高]
**核心结论**：[2-3 句综合判断]
**关注要点**：[需要持续监控的指标]
```

---

## 使用示例

### 示例 1：单国经济指标查询

**用户**：「查询中国 2020-2025 年的 GDP 和 CPI 数据」

**执行**：

1. **需求分析**：单国 + 两个 IFS 指标 + 年度数据
2. **并行查询**：
   - `fetch_ifs_data(freq="A", country="CN", indicator="NGDP_XDC", start=2020, end=2025)`
   - `fetch_ifs_data(freq="A", country="CN", indicator="PCPI_IX", start=2020, end=2025)`
3. **输出**：使用 **模板 A** 展示表格 + 洞察

### 示例 2：多国通胀对比

**用户**：「比较 G7 国家最近 5 年的通胀率」

**执行**：

1. **需求分析**：多国对比 + CPI + 年度
2. **查询**：
   - `fetch_ifs_data(freq="A", country="US+JP+DE+GB+FR+IT+CA", indicator="PCPI_IX", start=2020, end=2025)`
3. **输出**：使用 **模板 B** 展示横向对比表 + Key Insights

### 示例 3：双边贸易分析

**用户**：「获取中国和美国的双边贸易数据，过去 10 年」

**执行**：

1. **需求分析**：双边贸易 → DOT 数据集
2. **并行查询**：
   - `fetch_dot_data(freq="A", country="CN", indicator="TXG_FOB_USD", counterpart="US", start=2015, end=2025)` — 中国对美出口
   - `fetch_dot_data(freq="A", country="CN", indicator="TMG_CIF_USD", counterpart="US", start=2015, end=2025)` — 中国自美进口
3. **计算**：贸易差额 = 出口 - 进口
4. **输出**：表格展示出口、进口、贸易差额趋势

### 示例 4：新兴市场风险评估

**用户**：「评估土耳其的金融风险」

**执行**：

1. **需求分析**：国家风险 → FSI + BOP + GFS + IFS 交叉
2. **先查指标**：
   - `list_indicators(dataset_id="FSI")` — 确认可用的金融稳健性指标
3. **并行查询**：
   - `fetch_fsi_data(freq="A", country="TR", indicator="[不良贷款率代码]", start=2020, end=2025)`
   - `fetch_bop_data(freq="A", country="TR", indicator="BCA_BP6_USD", start=2020, end=2025)`
   - `fetch_ifs_data(freq="A", country="TR", indicator="PCPI_IX", start=2020, end=2025)`
   - `fetch_gfsmab_data(freq="A", country="TR", unit="XDC_R_B1GQ", indicator="[债务指标代码]", start=2020, end=2025)`
4. **输出**：使用 **模板 C** 展示风险评分矩阵

---

## 错误处理

| 情况 | 原因 | 解决方案 |
|------|------|----------|
| API 返回空数据 | 指标/国家代码错误 | 调用 `list_indicators` / `list_countries` 确认正确代码 |
| API 返回 503 | 超速率限制（~10 calls/5s） | 减少并发，加入间隔再重试 |
| 部分国家缺失数据 | 该国未按时报送 | 在结果中标注「数据缺失」，缩小时间范围重试 |
| 时间序列不完整 | 数据尚未发布 | 缩短 `end` 年份，说明最新可用年份 |
| 不确定该用哪个数据集 | 需求模糊 | 参考「数据集选择矩阵」，必要时询问用户 |
| MCP Server 无响应 | 网络问题 | 提示用户检查网络连接或代理配置 |

---

## 重要原则

1. **速查表优先**：先查本文档的速查表，找不到再调用 `list_indicators` / `list_countries`
2. **并行高效**：多个独立的数据查询应并行执行，减少等待时间
3. **标注数据来源**：每个数据表格标注 `数据来源：IMF [具体数据集]`
4. **标注数据频率**：明确说明数据是年度 (A)、季度 (Q) 还是月度 (M)
5. **注意数据滞后**：IMF 数据通常有 2-6 个月的滞后，最新数据可能尚未发布
6. **单位一致性**：确保比较数据使用相同单位（本币 vs 美元、绝对值 vs 百分比）
7. **表格化呈现**：时间序列数据必须以表格形式呈现，便于对比
8. **区分数据与推断**：IMF 原始数据为「事实」，基于数据的分析为「推断」
9. **报告语言**：综合分析使用中文，技术术语和代码保留英文
10. **多国代码连接**：多国查询时国家代码用 `+` 连接，如 `"CN+US+JP"`
11. **WEO 限制**：当前 MCP 不支持 WEO 预测数据，如需预测请使用 `web-research` 联网检索