imf-mcp-server

---

概述

涵盖 190 个国家的 IMF 宏观经济数据：世界经济展望预测、国际收支、CPI、汇率、国民账户以及数百个其他数据集。浏览目录、解析维度代码、查询时间序列，并对大型多国结果运行 SQL。无需 API 密钥。

工具

工具	描述
imf_list_databases	列出 IMF SDMX 数据流，可选按词语筛选
imf_get_database	获取数据流的维度和代码列表，以将术语解析为 SDMX 代码
imf_query_dataset	按维度键和时间范围查询数据流
imf_dataframe_describe	列出由 imf_query_dataset 暂存的 DataCanvas 表和列
imf_dataframe_query	对暂存的 DataCanvas 表运行只读 SQL SELECT 查询
imf_dataframe_drop	移除一个暂存表或视图；默认禁用

资源

资源	描述
imf://database/{dataflow_id}	单个数据流的发现元数据：维度、代码列表预览和 key_format

功能参考

imf_list_databases _工具

• filter 会保留 ID、名称或描述中包含所有词语的数据流（按空格和逗号拆分，不区分大小写）；除非设置 include_vintages=true，否则会排除 WEO_2025_OCT_VINTAGE 等 vintage 快照
• 使用 limit（默认值为 50）和 offset 分页；每页最多包含 200 条。若 limit 较大（最高为 1,000），则会返回 requested_limit/applied_limit。total_count 和 returned_count 分别报告匹配项数和当前页的条目数
• 描述会截断至 200 个字符；imf_get_database 会返回完整文本

---

imf_get_database _工具

• 将术语解析为 SDMX 维度代码（国家使用 ISO 3 字母代码：USA，而非 US），并返回 key_format，即 imf_query_dataset 所需的点分隔维度顺序
• 代码列表预览最多包含 50 个条目；设置 dimension_id 可对一个维度分页，使用 limit/offset（每页最多 200 个条目，next_offset 会指出其余条目的位置），并设置 codelist_filter，仅保留 ID 或名称中包含所有词语的代码
• available_only=true 时，仅对数据流已发布的代码分页，并提供序列数量和时间覆盖范围；如果未提供 agency_id/version，则会自动检测

---

imf_query_dataset _工具

• 使用按 DSD 顺序排列的点分隔键，其中 + 会合并某一位置的代码，* 会匹配该位置的所有代码；代码和 dataflow_id 不区分大小写。start_period/end_period 接受 YYYY、YYYY-SN、YYYY-QN、YYYY-MM 或 YYYY-MM-DD；last_n_observations（1–1,000,000）会保留每个序列最后 N 个观测值
• 返回 time_period、value、status 和序列属性（已发布时包含 unit、scale、decimals、reference_period），每个序列对应一个 series_metadata 条目。响应限制为 100,000 个字符：使用 DataCanvas 时，较大的结果会转存至其中（output_mode: "canvas" 会强制暂存，staged 会报告存储状态）；不使用 DataCanvas 时，会返回最早的观测值，并设置 truncated: true 和 retrieval_guidance
• 键和范围错误包括 invalid_key_code（附带最接近的有效代码）、wildcard_in_code_list、key_too_long、response_too_large、no_data 和 no_data_in_range；如果 + 键仅部分返回结果，则会在 missing_series 中列出其余序列。上游故障包括 data_unavailable 和 rate_limited，二者均可在 45 秒调用时限内重试

---

imf_dataframe_describe _工具

• 列出所有已暂存的表，并提供行数、列名和 DuckDB 类型
• 需要来自返回 staged: true 的 imf_query_dataset 调用的 canvas_id；请在调用 imf_dataframe_query 前先调用此工具
• 仅在 CANVAS_PROVIDER_TYPE=duckdb 时列出，与其他 dataframe 工具相同

---

imf_dataframe_query _工具

• 每次调用执行一条只读 SQL SELECT；接受以 WITH … SELECT 开头的语句，拒绝 DML 和 DDL
• 结果先受画布行数限制（默认 10,000），再受 100,000 个字符的响应限制；truncated: true 表示结果被任一限制截断。使用稳定的 ORDER BY 并结合 LIMIT/OFFSET 分页
• 超大单元格会在文本表格中截断，但 structuredContent 会保留所有值；即使如此，若单行仍超出限制，则会返回 response_too_large
• 仅在 CANVAS_PROVIDER_TYPE=duckdb 时列出

---

imf_dataframe_drop _工具

• 从画布中移除一个指定名称的表或视图；必须使用 imf_dataframe_describe 提供的准确名称
• 重复删除或删除不存在的对象时，会返回 dropped: false，而非错误
• 默认禁用；设置 CANVAS_PROVIDER_TYPE=duckdb 的同时设置 IMF_ENABLE_DATAFRAME_DROP=true，即可注册此工具

---

imf://database/{dataflow_id} _资源

• 提供每个维度最多 50 个代码列表条目，以及计数、key_format、名称和描述
• dataflow_id 来自 imf_list_databases；continuation 元数据会指向 imf_get_database，以获取超出预览范围的代码列表

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志记录。

IMF 专属功能：

• 无需密钥即可访问公开的 IMF SDMX 3.0 门户
• 类型化的 SDMX 3.0 客户端，每次查询前都会根据 DSD 验证键中的维度数量
• 在会话期间缓存数据流目录和可用性约束
• 使用 DuckDB 支持的 DataCanvas 溢写大型多国家或长时间范围的结果

便于 Agent 使用的输出：

• 代码表条目同时包含机器代码和易读标签
• 每个数据流响应中的 key_format 都会说明维度顺序
• 观测值包含每个数据流的 status 标记（例如 T、C、NA），以提示数据质量注意事项
• 分别报告 staged 和 truncated；暂存的结果会附带 canvas_id、table_name 和检索指南

开始使用

公共托管实例

可使用公共实例：https://imf.caseyjhand.com/mcp，无需安装。通过 Streamable HTTP 将任意 MCP 客户端指向该实例：

{
  "mcpServers": {
    "imf-mcp-server": {
      "type": "streamable-http",
      "url": "https://imf.caseyjhand.com/mcp"
    }
  }
}

自托管 / 本地部署

无需 API 密钥。将以下内容添加到 MCP 客户端配置文件中。

{
  "mcpServers": {
    "imf-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/imf-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

也可以使用 npx（无需 Bun）：

{
  "mcpServers": {
    "imf-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/imf-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

也可以使用 Docker：

{
  "mcpServers": {
    "imf-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/imf-mcp-server:latest"
      ]
    }
  }
}

要对大型结果集启用 SQL 分析，请在 env 块中添加 CANVAS_PROVIDER_TYPE=duckdb。仅当 Agent 需要能够移除暂存表时，才添加 IMF_ENABLE_DATAFRAME_DROP=true。

使用 Streamable HTTP 时，请设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 无需 API 密钥。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/imf-mcp-server.git

2. 进入目录：

cd imf-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

cp .env.example .env
# edit .env as needed — no required vars for basic use

配置

变量	描述	默认值
CANVAS_PROVIDER_TYPE	设置为 duckdb，以启用 DataCanvas 溢写和数据帧工具。	—
IMF_ENABLE_DATAFRAME_DROP	注册 imf_dataframe_drop。	false
IMF_BASE_URL	IMF SDMX 3.0 基础 URL。	https://api.imf.org/external/sdmx/3.0
IMF_REQUEST_TIMEOUT_MS	每个请求的超时时间，单位为毫秒。	30000
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务的端口。	3010
MCP_SESSION_MODE	HTTP 会话处理方式：stateful、stateless 或 auto。	stateless
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
OTEL_ENABLED	启用 OpenTelemetry 埋点。	false

完整的可选覆盖项列表请参阅 .env.example。

运行服务

本地开发

• 构建并运行：

  bun run rebuild
  
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t imf-mcp-server .
docker run --rm -p 3010:3010 imf-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/imf-mcp-server。默认会安装 OpenTelemetry 对等依赖项；构建时添加 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

项目结构

目录	用途
src/index.ts	createApp() 入口点 — 注册工具/资源并初始化服务。
src/config/server-config.ts	使用 Zod 解析并验证特定于服务的环境变量。
src/mcp-server/tools/definitions/	工具定义（*.tool.ts）。
src/mcp-server/resources/definitions/	资源定义（*.resource.ts）。
src/services/canvas/	DataCanvas 访问器 — 封装框架的 canvas 实例。
src/services/imf-sdmx/	IMF SDMX 3.0 API 客户端 — 数据流目录、DSD 获取、数据查询。
tests/	与 src/ 结构对应的单元测试和集成测试。
docs/	设计说明和目录树。

开发指南

开发指南和架构规则请参阅 CLAUDE.md/AGENTS.md。简要说明：

• 处理程序抛出错误，框架负责捕获 — 工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围内的日志，使用 ctx.state 存储租户范围内的数据
• 通过 src/mcp-server/*/definitions/index.ts 中的 barrel 文件注册新工具和资源
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不伪造缺失字段

数据来源

数据来源于国际货币基金组织 SDMX 3.0 门户，并遵循 IMF 版权和使用条款。IMF 的条款允许在注明出处的情况下重新分发统计数据。每个返回数据的工具响应都包含一个 source 字段，其中注明所需的来源信息：Source: International Monetary Fund, <dataflow name>, https://data.imf.org/。

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0 — 详情请参阅 LICENSE。