worldbank-mcp-server

---

概述

世界银行开放数据：29,500 多项发展指标、贫困与不平等估算数据，以及世界银行的贷款项目。搜索指标、查询各国时间序列、获取贫困指标，并搜索现行和历史项目。无需 API 密钥。

工具

工具	说明
worldbank_list_topics	列出世界银行全部 21 个主题领域及其说明
worldbank_list_sources	分页列出世界银行 70 多个数据来源（数据集）
worldbank_list_countries	列出国家和地区汇总项及其 ISO 代码、地区、收入水平、贷款类型和坐标；可按地区、收入水平和贷款类型筛选
worldbank_get_country	根据 ISO2、ISO3 或汇总代码获取指定国家或地区汇总项的完整元数据
worldbank_search_indicators	按关键词、主题领域或来源搜索 29,500 多项指标目录
worldbank_get_indicator	获取单项指标的完整元数据：名称、说明、来源、单位和主题领域
worldbank_get_data	查询一个或多个国家在指定时间范围、最近 N 个周期或每个国家最近 N 个非空值中的指标数值；支持按年、季度或月查询
worldbank_get_poverty	从贫困与不平等平台获取各经济体及 PIP 地区、收入组、贷款组和脆弱性组汇总项在任意贫困线下的贫困发生率、贫困缺口和贫困严重度，以及基尼系数和各十分位组占比
worldbank_search_projects	按文本、国家、地区、状态、融资窗口和董事会批准日期搜索世界银行贷款项目组合

资源

资源	描述
worldbank://indicator/{indicatorId}	按 ID 查询指标元数据——名称、描述、来源、单位和主题
worldbank://country/{countryCode}	按 ISO2、ISO3 或汇总代码查询国家元数据——地区、收入水平、首都和坐标

功能参考

worldbank_list_topics _工具

• 无需输入——返回包含 21 个主题的完整固定分类
• 主题 ID（例如，1 农业、3 经济与增长）可用于 worldbank_search_indicators 的 topic_id

---

worldbank_list_sources _工具

• 分页列出 70 多个世界银行数据来源（数据集）；每页最多 100 条
• 每条包含 ID、名称、简称、最后更新日期，以及数据/元数据的可用性
• 来源 ID（例如，世界发展指标对应 2）可用于 worldbank_search_indicators 的 source_id

---

worldbank_list_countries _工具

• 可按地区代码（EAS、SSF 等，以及 AFE、EUU、LDC 等成员分组）、收入水平（LIC、LMC、UMC、HIC）和贷款类型（IDX、IBD、IDB、LNX）筛选，条件之间按 AND 组合；每页最多 150 条（约 50 KB）
• 返回 ISO 代码、地区、收入水平、贷款类型、首都和坐标；无效的地区或收入代码会触发类型化的 invalid_filter 错误
• 默认仅返回单个国家——设置 include_aggregates=true 可加入地区、收入组和全球汇总项，并标记为 isAggregate

---

worldbank_get_country _工具

• 接受一个 ISO2（US）、ISO3（USA）或世界银行汇总代码（EAS、HIC、WLD）——all 或列表会被拒绝，并返回 multiple_countries
• 返回地区、收入水平、贷款类型、首都和坐标
• 类型化的 country_not_found 错误会提供恢复提示，指向 worldbank_list_countries

---

worldbank_search_indicators _工具

• 必须至少提供 query、topic_id 或 source_id 之一；每个关键词都必须匹配指标 ID、名称或描述，且关键词顺序不限；每页最多 100 条
• 结果按匹配程度排序：先是 ID/名称完全匹配项，再是名称以该短语开头的项，然后是宽松匹配项，最后是仅描述匹配项；每个级别中，世界发展指标系列优先，同一系列也优先于其细分指标（SP.DYN.LE00.IN 排在 SP.DYN.LE00.FE.IN 之前）
• 每个指标 ID 仅出现一次，并附带描述的前 150 个字符；worldbank_get_indicator 会返回完整描述

---

worldbank_get_indicator _工具

• 每次调用仅接受一个指标 ID，由字母、数字、.、_ 或 - 组成——all、列表或任何其他字符都会被拒绝
• 返回描述、单位、来源数据集、来源组织和主题；保留描述中的 HTML 换行，剥除其他标记
• 类型化的 indicator_not_found 错误会指向 worldbank_search_indicators

worldbank_get_data _工具

• countries 可使用 ISO2、ISO3、汇总代码、WLD，或单独使用 all；date_range（一个年份、季度或月份，或同一类型的范围）、mrv（各国家/地区最近的 N 个时段）和 mrnev（各国家/地区自身最近的 N 个值）三者最多指定一个——例如，厄立特里亚的人均 GDP 在 2011 年有数据，而 mrv 会返回 2025 年和 null；frequency（annual、quarterly、monthly）用于选择发布多个时段的指标所采用的时段形式（例如，肯尼亚的 CPTOTSAXN，monthly、mrv: 3 → 2026M07–M05）；每页最多 200 条观测（约 50 KB）
• 每行都包含两个国家/地区代码、isAggregate，以及缺失单元格对应的 value: null；每页还包含 nullCount 和作为数据版本标记的 lastUpdated。每次读取 date_range、mrv 和 mrnev 时，都会检查其他查询是否有缓存答案，并重新读取一次；连续两次失败时，将返回 upstream_inconsistent 错误，而不是提供结果
• 标准端点不提供的指标（WDI Database Archives、PEFA、ICP、GDLD、International Debt Statistics: DSSI、Food Prices for Nutrition）来自各自的数据集；sourceScoped 会披露所应用的发布版本、分类、部门或对应领域（dimension_value）

---

worldbank_get_poverty _工具

• 可使用 ISO3 或 ISO2 代码指定经济体，包括 PIP 仅以模型估算值发布的经济体（AFG），以及 PIP 的汇总项：WLD、地区（SSF、AFE）、收入组（LMIC/LMC）、贷款组（IDX、IDB、IBD、REST）和脆弱性组（FCVY、FCVN；对于 WDI 的 FCS，会拒绝请求并提示使用 FCVY，但不会声称两者的成员范围相同）；year 可指定年份、all 或 MRV；可指定任意 poverty_line，默认使用所应用的 PPP 版本对应的国际贫困线；每页最多 70 条估算数据（约 50 KB）
• 包含贫困发生率、贫困缺口、贫困严重程度和 Watts 指数，以及调查数据行中的基尼系数、对数均值偏差、极化程度和十分位份额；estimationType 用于区分调查数据行和补齐缺口的数据行，后者的不平等指标字段为 null；isAggregate 用于标记汇总行
• fill_gaps（默认为 true）用于包含补齐缺口的年份；welfare_type 和 reporting_level 用于缩小经济体结果范围，ppp_version 用于选择 PPP 版本

---

worldbank_search_projects _工具

• 自由文本 query 与 countries（ISO3、ISO2 或世界银行地区代码，例如 3A）、region、status、financial_type 和董事会批准时间范围（approved_from/approved_to）组合使用；每页最多 80 个项目，按批准时间从新到旧排序
• 返回 ID、名称、国家/地区、区域、状态、日期、承诺金额及其 IBRD、IDA 和赠款部分、融资窗口、部门和 URL；countryCodes 可串联其他工具；代码无效或查询无法解析时，会返回类型化的 invalid_country_code / invalid_query 错误；结果为空时会指出导致结果为空的筛选条件
• include_abstract（默认关闭）会添加摘要，每页 8 个项目，每个摘要截断至 5,000 个字符

---

worldbank://indicator/{indicatorId} _资源

• 以 application/json 格式提供指标元数据——名称、描述、单位、来源数据集、来源机构和主题
• indicatorId 来自 worldbank_search_indicators；未知 ID 会返回带有恢复提示的类型化未找到错误；上游服务中断或超时时会保留其自身错误分类，而不会被判定为 ID 错误

---

worldbank://country/{countryCode} _资源

• 以 application/json 格式提供国家/地区或汇总项元数据——ISO 代码、区域、收入水平、首都和坐标
• 接受一个 ISO2、ISO3 或世界银行汇总代码——不接受 all 或代码列表；未知代码会返回类型化未找到错误，与临时上游故障区分开来

功能

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

World Bank 专属功能：

• 全面覆盖 World Bank Open Data 的三个独立上游 API——Indicators API、Poverty and Inequality Platform，以及 Projects 贷款组合
• 提供 60 多年的发展数据（PIP 数据覆盖范围始于 1963 年），涵盖 29,500 多项指标、200 多个国家及区域汇总数据
• 对指标目录执行客户端关键词搜索，因为上游的 searchterm 参数无法进行筛选
• 透明呈现空值——展示 null 观测值和 nullCount，而非静默丢弃
• 每个国家/地区和数据行都包含 isAggregate 标志，用于区分单个国家和汇总实体

面向 Agent 的输出：

• 在描述中加入工具交叉引用——例如，worldbank_search_indicators 会指出可使用 worldbank_list_topics 获取主题 ID，worldbank_get_data 会指出可使用 worldbank_search_indicators 查找指标
• 所有工具都采用结构化错误约定，包含带类型的 reason 代码和可执行的 recovery 提示
• 所有列表/搜索/数据工具均使用一致的分页元数据（totalCount、currentPage、totalPages）；请求超出末页时会提示有哪些页面

开始使用

公共托管实例

可使用公共实例：https://worldbank.caseyjhand.com/mcp，无需安装。通过 Streamable HTTP 将任意 MCP 客户端连接到此实例：

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

自托管 / 本地运行

将以下内容添加到 MCP 客户端配置文件中。

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

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

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

或使用 Docker：

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

若要使用 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 ≥24.0.0）。
• 无需 API 密钥——World Bank Open Data API 是公开的，无需身份验证。

安装

1. 克隆代码库：

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

2. 进入目录：

cd worldbank-mcp-server

3. 安装依赖：

bun install

4. 配置环境（可选）：

cp .env.example .env
# edit .env and set optional overrides

配置

所有配置都会在启动时通过 src/config/server-config.ts 中的 Zod 模式进行验证。环境变量：

变量	描述	默认值
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http	stdio
MCP_HTTP_PORT	HTTP 服务端口	3010
MCP_HTTP_HOST	HTTP 服务主机名	127.0.0.1
MCP_HTTP_ENDPOINT_PATH	MCP 服务挂载的 HTTP 端点路径	/mcp
MCP_PUBLIC_URL	用于 TLS 终止型反向代理部署的公共源地址覆盖值	无
MCP_AUTH_MODE	身份验证：none、jwt 或 oauth	none
MCP_SESSION_MODE	HTTP 会话处理方式：stateful、stateless 或 auto。服务在代码中声明为 stateless——它不保留任何会话状态——在此处设置的值会覆盖该声明	stateless
MCP_LOG_LEVEL	日志级别（debug、info、notice、warning、error）	info
LOG_TOOL_FAILURE_PAYLOADS	记录每次失败的工具调用的参数和结果，按键名进行脱敏，并限制为 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（默认 16384）。自由格式值中的密钥不会脱敏	false
STORAGE_PROVIDER_TYPE	存储后端：in-memory、filesystem、supabase、cloudflare-kv/r2/d1	in-memory
OTEL_ENABLED	启用 OpenTelemetry	false
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	启用 OTLP 日志导出（例如 http://localhost:4318/v1/logs）；基础变量 OTEL_EXPORTER_OTLP_ENDPOINT 不会启用日志导出	无
WORLDBANK_API_BASE_URL	World Bank Indicators API 基础 URL 覆盖值	https://api.worldbank.org/v2
WORLDBANK_PIP_BASE_URL	Poverty and Inequality Platform API 基础 URL 覆盖值	https://api.worldbank.org/pip/v1
WORLDBANK_PROJECTS_BASE_URL	Projects API 基础 URL 覆盖值	https://search.worldbank.org/api/v3
WORLDBANK_DEFAULT_PER_PAGE	列表、搜索和数据操作的默认分页大小；worldbank_get_data、worldbank_list_countries、worldbank_search_projects 和 worldbank_get_poverty 仍会将其限制在各自的分页上限内	50
WORLDBANK_CATALOG_CACHE_TTL_MS	进程内参考缓存的存留时间——关键词搜索背后的指标目录、isAggregate 背后的国家索引、按来源划分的国家代码和贫困 ISO2 代码、每个按来源划分的数据集的概念／国家／时期／维度列表，以及 ppp_version 背后的 PIP 版本列表、用于汇总代码的区域表，以及仅包含模型估算数据的经济体列表；0 会禁用所有缓存	3600000

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

运行服务

本地开发

• 构建并运行生产版本：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio
  

• 运行检查和测试：

  bun run devcheck  # Lint, format, typecheck, and more
  bun run test      # Runs the test suite
  

Docker

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

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

项目结构

目录	用途
src/mcp-server/tools	工具定义（*.tool.ts）。共有九个工具，涵盖主题、来源、国家、指标、数据、贫困和项目。
src/mcp-server/resources	资源定义。指标和国家元数据资源。
src/services/worldbank	World Bank Indicators API 服务层——API 客户端和领域类型。
src/services/pip	Poverty and Inequality Platform API 服务层——独立的客户端和领域类型。
src/services/projects	Projects API 服务层——独立的客户端和领域类型。
src/config	使用 Zod 解析和验证服务专用的环境变量。
tests/	单元测试和集成测试，结构与 src/ 对应。

开发指南

请参阅 CLAUDE.md，了解开发指南和架构规则。简要来说：

• 由处理程序抛出错误，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录日志，使用 ctx.state 存储数据
• 在 createApp() 数组中注册新工具和资源
• 封装外部 API 调用：校验原始数据 → 规范化为领域类型 → 返回输出架构；不要伪造缺失字段

参与贡献

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

bun run devcheck
bun run test

许可证

本项目采用 Apache 2.0 许可证。详情请参阅 LICENSE 文件。