oecd-mcp-server

---

概览

涵盖国民账户、就业、贸易、教育和健康领域的 1,500 多个数据集中的 OECD 统计数据。搜索数据集、检查其维度、查询观测值，并对大型多国家时间序列运行 SQL。无需 API 密钥。

工具

五个发现和数据工具，以及三个用于处理大型查询结果的 DataCanvas 工具：

工具	描述
oecd_list_agencies	列出 OECD SDMX 机构及其所属司局和各自发布的数据流数量
oecd_search_datasets	按关键词或主题搜索 1,500 多个 OECD 数据流
oecd_get_dataset_info	获取数据流的维度、键顺序和代码列表引用
oecd_get_dimension_values	获取某个维度的有效代码和标签（国家、指标、频率）
oecd_query_dataset	按维度键和时间范围筛选并获取观测值；大型结果会转存到 DataCanvas
oecd_dataframe_describe	列出先前由 oecd_query_dataset 转存的 DataCanvas 表和列
oecd_dataframe_query	对 DataCanvas 表运行只读 SQL SELECT
oecd_dataframe_drop	分析完成后删除暂存的 DataCanvas 表或视图 — 需通过 OECD_DATAFRAME_DROP_ENABLED=true 启用

资源

资源	描述
oecd://dataflow/{agency_id}/{flow_id}	单个 OECD 数据流的维度元数据 — 与 oecd_get_dataset_info 内容相同

所有资源数据也可通过工具访问。使用 oecd_get_dataset_info 可获取相同内容。

能力参考

oecd_list_agencies _工具

• 无输入；返回所有机构 ID（例如 OECD.SDD.NAD）、对应的局名称和数据流数量，并按数量排序
• 通过同一目录发布数据流的 OECD 以外发布方（ESTAT、IAEG-SDGs）没有局名称

---

oecd_search_datasets _工具

• query 会与数据流名称和描述进行分词匹配；可选的 agency_id 用于限定范围；limit（1–100）和 offset 用于分页，并返回 total_matches
• 每条结果都包含其 flow_ref（其他所有工具使用的标识符）和 matched_in（name、description 或 both）

---

oecd_get_dataset_info _工具

• 接受 flow_ref；按键顺序返回每个维度、对应的概念名称和代码列表引用，以及供 oecd_query_dataset 使用的 key_example
• 对不是数据流引用的字符串返回 invalid_flow_ref 错误；对 OECD 未发布的数据流返回 dataflow_not_found 错误

---

oecd_get_dimension_values _工具

• 接受 flow_ref 和 dimension_id；可选的 query 会对代码和标签进行子字符串匹配
• limit（1–500，默认值为 50）和 offset 用于对匹配结果分页；有更多结果时会返回完整匹配数

---

oecd_query_dataset _工具

• flow_ref 加上以点分隔的 key（多个值用 + 表示，空段作为通配符），以及可选的 start_period / end_period
• 每条观测值占一行，每个维度和属性各占一列；value 已预先乘以 value_scale
• 大型结果会溢出到 DataCanvas，并返回 truncated: true、canvas_id 和 table_name；没有画布时，所有行都会保留在 structuredContent 中，只有渲染后的表格会受到限制（content_table_capped）
• 溢出时会附带一条 notice，其中会标明画布和表格名称：使用 oecd_dataframe_describe 检查列，然后使用 oecd_dataframe_query 对完整结果执行 SQL。适合当前限制的结果不会分配新画布；显式提供的 canvas_id 仍会经过验证。

---

oecd_dataframe_describe _工具

• 接受 oecd_query_dataset 返回的 canvas_id；列出每个暂存表和视图的行数、列名及类型

---

oecd_dataframe_query _工具

• canvas_id 加上一条只读 SQL SELECT；写入操作、DDL 和系统目录访问都会被拒绝
• 返回的行数不超过画布行数上限；row_count 报告完整行数

---

oecd_dataframe_drop _工具

• canvas_id 加上 oecd_dataframe_describe 列出的 table_name；返回被删除对象的 kind 和 remaining_tables
• 需主动启用：该工具会列出，但除非 OECD_DATAFRAME_DROP_ENABLED=true，否则无法调用

---

oecd://dataflow/{agency_id}/{flow_id} _资源

• 内容与 oecd_get_dataset_info 相同，格式为 application/json
• {flow_id} 的格式为 {dsd_id}@{df_id}，其中 @ 编码为 %40（例如 oecd://dataflow/OECD.SDD.NAD/DSD_NAAG%40DF_NAAG_I），也可以是纯 {df_id}

功能

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

OECD 专属功能：

• 无密钥访问——无需 API 密钥；OECD SDMX 2.1 REST API 完全公开
• 覆盖 20 多个 OECD 统计部门的 1,500 多个数据流（国民账户、就业、通胀、贸易、教育、卫生、环境、税收、不平等）
• 端到端解析委托数据流和代码列表修订版本——如果 OECD 在一个服务根目录中编录某个数据流，却在另一个服务根目录中定义它，则会沿用目录自身的链接来获取结构、代码和观测值；代码取自数据结构指定的修订版本，而非端点当前的最新版本
• AllDimensions 观测模式——一次性将 SDMX-JSON 解码为扁平行对象，无需重建嵌套序列键
• oecd_query_dataset 会将大型观测集（多国家时间序列）物化到 DuckDB DataCanvas，以便在对话中进行 SQL 分析；三个 oecd_dataframe_* 工具可对其进行操作，并且需要 CANVAS_PROVIDER_TYPE=duckdb

面向 Agent 的输出：

• 支持工作流的工具界面——搜索返回的 flow_ref 可直接传入信息、值和查询工具，无需重建
• 溢出提示——truncated: true + canvas_id 会告知 Agent 改用 SQL，而不是解析被截断的内联列表
• 在服务端完整解码 SDMX——Agent 看到的是 { REF_AREA: "United States", MEASURE: "Gross domestic product", UNIT_MULT: "Billions", value: 26054614000000, value_scale: 1000000000 }，而不是原始索引数组

入门

公共托管实例

公共实例位于 https://oecd.caseyjhand.com/mcp，无需安装即可使用。该实例提供 Streamable HTTP；每个客户端的配置格式各不相同。

Claude Code 配置：

claude mcp add --transport http oecd-mcp-server https://oecd.caseyjhand.com/mcp

Cline 配置（cline_mcp_settings.json）：

{
  "mcpServers": {
    "oecd-mcp-server": {
      "type": "streamableHttp",
      "url": "https://oecd.caseyjhand.com/mcp"
    }
  }
}

Cursor 配置（mcp.json）：

{
  "mcpServers": {
    "oecd-mcp-server": {
      "url": "https://oecd.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop 可在 Settings → Connectors 下添加远程服务。

自托管 / 本地运行

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

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

也可使用 npx（无需 Bun）：

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

也可使用 Docker：

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

大型查询结果的 DataCanvas SQL 分析默认已启用。要关闭它，请添加 CANVAS_PROVIDER_TYPE=none：

{
  "mcpServers": {
    "oecd-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/oecd-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "CANVAS_PROVIDER_TYPE": "none"
      }
    }
  }
}

对于 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 密钥——OECD SDMX 是免费公开的 API。

安装

1. 克隆代码库：

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

2. 进入目录：

cd oecd-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

cp .env.example .env
# edit .env — most vars are optional; no API key required

配置

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

变量	描述	默认值
OECD_BASE_URL	OECD SDMX REST API 基础 URL。必须是可直接响应的 https 来源，不会跟随重定向，因此纯文本 http:// 来源会直接失败，而不会升级为 https。	https://sdmx.oecd.org/public/rest
OECD_TIMEOUT_MS	每次请求的超时时间，单位为毫秒。	30000
CANVAS_PROVIDER_TYPE	Canvas 引擎。使用 duckdb 时，大型 oecd_query_dataset 结果会溢出到可查询的表中，而不只是限制渲染的预览；使用 none 时，所有行仍会在 structuredContent 中返回，只有渲染的表格会受到限制。	duckdb
OECD_DATAFRAME_DROP_ENABLED	设置为 true 以注册 oecd_dataframe_drop。关闭时，该工具会标记为禁用，客户端无法调用。	false
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务的端口。	3010
MCP_SESSION_MODE	HTTP 会话模式：stateful、stateless 或 auto。源码中将服务声明为 stateless——它不保留每个会话的状态，DataCanvas 句柄由 canvas_id 标识——因此只有要覆盖该设置时才需要设置此项。	stateless
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	记录每次失败的工具调用参数和结果，按键名脱敏，并限制在 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（默认值为 16384）字节以内。自由格式值中的机密不会被脱敏。	false
OTEL_ENABLED	启用 OpenTelemetry 插桩。	false

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

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  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 oecd-mcp-server .
docker run --rm -p 3010:3010 oecd-mcp-server

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

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册工具和资源并初始化服务。
src/config/	使用 Zod 解析并验证服务专用的环境变量。
src/mcp-server/tools/definitions/	工具定义（*.tool.ts）——用于 OECD 数据发现、检索和 DataCanvas 分析的八个工具。
src/mcp-server/resources/definitions/	资源定义（*.resource.ts）——oecd://dataflow 资源。
src/services/oecd-http/	共享的 OECD 获取边界——其中包含供下方两个服务使用的超时和重试分类修正、每个被委派的服务根路径在访问前都会通过的来源检查、对配置主机之外任何重定向的拒绝，以及一项分类机制，可让上游拒绝在每个工具和资源中返回相同的声明原因。
src/services/oecd-structure/	OECD SDMX 结构服务——数据流、数据结构、代码列表。
src/services/oecd-data/	OECD SDMX 数据服务——观测值、SDMX-JSON 解码、DataCanvas 溢出。
src/services/canvas-accessor/	DataCanvas 访问器——向工具注册并公开框架 Canvas 实例。
tests/	与 src/ 结构对应的单元测试和集成测试。

开发指南

请参阅 CLAUDE.md 了解开发指南和架构规则。简而言之：

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

贡献

欢迎提交 Issue——请参阅 CONTRIBUTING.md，了解怎样的 Issue 才便于采取行动；并参阅 CODE_OF_CONDUCT.md，了解我们的协作方式。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0——详情请参阅 LICENSE。