federal-reserve-mcp-server

---

概述

来自 FRED 的经济数据。FRED 是圣路易斯联邦储备银行的数据库，收录了约 80 万条关于产出、价格、就业、货币、利率、住房和贸易的时间序列。搜索序列、获取观测值、浏览类别和发布内容，并对大型结果运行 SQL 查询。

工具

工具	描述
fedreserve_search_series	对 FRED 序列标题、标签和备注进行全文搜索
fedreserve_get_series	获取一个或多个序列的元数据——标题、单位、频率和观测范围
fedreserve_get_observations	获取一个或多个序列的日期和数值观测值，并支持按日期范围和单位转换筛选
fedreserve_browse_categories	浏览 FRED 类别树
fedreserve_get_release	按 ID 或名称搜索查找 FRED 发布内容及其相关序列
fedreserve_dataframe_describe	列出活跃的 DataCanvas 数据框及其来源、架构和行数
fedreserve_dataframe_query	通过 DuckDB SQL 查询已注册的 DataCanvas 数据框
fedreserve_dataframe_drop	按名称删除 DataCanvas 数据框（需主动启用）

功能参考

fedreserve_search_series _tool

• 支持全文搜索或按序列 ID 搜索，并可使用 frequency、units、seasonal_adjustment 和 tag_names 筛选；filter_variable 和 filter_value 必须同时提供，否则调用将返回 invalid_filter
• 通过 limit（默认值和最大值均为 1000）和 offset（最大值为 4999；FRED 将可搜索结果上限设为 5000）进行分页
• 如有数据，输出包含 active_filters 和 popularity（0–100）；若结果为空，请尝试扩大查询范围或浏览类别

---

fedreserve_get_series _工具

• 每次可接受 1 个系列 ID，或最多 50 个系列 ID
• 返回每个系列的标题、单位、频率、季节调整、观测范围、热度和备注
• 批量请求中的失败 ID 会连同错误消息放入 failed 数组；单个无法解析的 ID 会抛出 series_not_found

---

fedreserve_get_observations _工具

• 可接受 1 个或最多 10 个系列 ID，并支持 observation_start / observation_end（YYYY-MM-DD）、原生单位转换，以及通过 aggregation_method（avg、sum、eop）降采样频率
• 返回日期/值观测结果（值为保留末尾零的字符串），并提供每个系列的失败信息
• 多系列或超过 500 行的结果会存入 DataCanvas 表格，并提供 20 行预览；notice 中会注明 dataset.name 以及接下来要运行的 fedreserve_dataframe_describe 和 fedreserve_dataframe_query 调用。没有画布时，会返回经过截断的内联预览

---

fedreserve_browse_categories _工具

• 省略 category_id 可从根目录（ID 0）开始；返回类别及其子类别，或在叶节点类别下返回最多 10 个示例系列
• 未知的 category_id 会抛出 category_not_found

---

fedreserve_get_release _工具

• 必须且只能指定 release_id 或 release_search（不区分大小写的名称子字符串）之一
• 返回发布名称、链接、备注、接下来安排的 5 个日期，以及分页的系列列表（series_limit 最大为 1000，series_offset）
• 名称不明确时会返回最多 10 个 search_alternatives；请使用确切的 release_id 重试

---

fedreserve_dataframe_describe _工具

• 按创建时间从新到旧列出活动 DataCanvas 数据帧，或根据 name 列出一个数据帧
• 每个条目都包含 source_tool、query_params、created_at、expires_at、row_count、truncated / max_rows 和 column_schema

---

fedreserve_dataframe_query _工具

• 对 df_<id> 表运行一条只读 DuckDB SELECT 语句（支持联接、聚合、窗口函数和 CTE）；外部文件、系统目录和引擎设置函数会被禁止
• row_limit 限制返回的行数（默认 1000，最大 10000），preview 设置内联示例；BIGINT 结果会序列化为字符串
• register_as 会将结果保存为具有独立 TTL 的新数据帧

---

fedreserve_dataframe_drop _工具

• 需选择启用：通过 FRED_DATAFRAME_DROP_ENABLED=true 启用，否则会注册为禁用状态
• 提前删除指定的数据帧；如果数据帧不存在，则返回 dropped: false

功能

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

FRED 专属功能：

• 需要用于 FRED API 的 FRED_API_KEY（每分钟最多 120 次请求）
• 单位转换和频率降采样会在 FRED 端基于完整系列历史数据运行
• 大型观测结果会存入可通过 SQL 查询的 DataCanvas 表格
• 数据帧工具需要 CANVAS_PROVIDER_TYPE=duckdb，否则会报告 canvas_unavailable

适合 Agent 使用的输出：

• 部分失败：fedreserve_get_series 和 fedreserve_get_observations 会返回每个 ID 对应的 failed 行，而不会导致整个请求失败
• 发布名称不明确时会返回 search_alternatives，而非猜测结果
• 每个数据帧都包含 source_tool、query_params 和 TTL 字段
• 没有 DataCanvas 时，fedreserve_get_observations 会返回经过截断的内联预览，并附带说明性 message

快速开始

将以下内容添加到 MCP 客户端配置文件中。请在 research.stlouisfed.org/docs/api/api_key.html 获取免费的 FRED API 密钥。

{
  "mcpServers": {
    "federal-reserve-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/federal-reserve-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "FRED_API_KEY": "your-api-key"
      }
    }
  }
}

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

{
  "mcpServers": {
    "federal-reserve-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/federal-reserve-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "FRED_API_KEY": "your-api-key"
      }
    }
  }
}

也可以使用 Docker：

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

对于 Streamable HTTP，请设置传输方式并启动服务：

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

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 从 stlouisfed.org 获取免费的 FRED API 密钥。该密钥的请求速率限制为每分钟 120 次。

安装

1. 克隆仓库：

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

2. 进入目录：

cd federal-reserve-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

cp .env.example .env
# edit .env and set FRED_API_KEY

配置

启动时会通过 src/config/server-config.ts 中的 Zod 模式验证所有配置。

变量	描述	默认值
FRED_API_KEY	必填。 从 stlouisfed.org 获取的 API 密钥。	—
FRED_BASE_URL	覆盖 FRED API 基础 URL。	https://api.stlouisfed.org/fred
FRED_DATASET_TTL_SECONDS	DataCanvas 观测值表的 TTL，单位为秒。	86400
FRED_DATAFRAME_DROP_ENABLED	设置为 true 以启用 fedreserve_dataframe_drop；否则注册为禁用状态。	false
CANVAS_PROVIDER_TYPE	设置为 duckdb，以启用对观测结果进行 DataCanvas SQL 查询。	—
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_SESSION_MODE	HTTP 会话模式：auto、stateful 或 stateless。	stateless
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<project-root>/logs
STORAGE_PROVIDER_TYPE	存储后端。	in-memory
OTEL_ENABLED	启用 OpenTelemetry 埋点。	false
OTEL_EXPORTER_OTLP_ENDPOINT	用于跟踪（/v1/traces）和指标（/v1/metrics）的 OTLP 基础 URL。	—
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	OTLP 日志端点（未设置时不会启用日志）。	—
LOG_TOOL_FAILURE_PAYLOADS	记录失败的工具参数和结果，并对键名进行脱敏；自由格式值中的机密信息不会脱敏。	false
LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES	每个记录负载的字节数上限。	16384

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

设置 CANVAS_PROVIDER_TYPE=duckdb，即可对观测值表执行 SQL 查询。npm 安装包和 Docker 镜像都包含 DuckDB 运行时。便携版 Claude Desktop 程序包不包含原生绑定；如需使用 canvas 模式，请通过 npm 或 Docker 安装。

运行服务

本地开发

• 构建并运行：

  # 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 federal-reserve-mcp-server .
docker run --rm -e FRED_API_KEY=your-key -e MCP_TRANSPORT_TYPE=http -p 3010:3010 federal-reserve-mcp-server

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

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册工具并初始化服务。
src/config	使用 Zod 解析和验证服务专属环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）。包含 FRED 领域和 DataCanvas 的 8 个工具。
src/services/fred	FRED API 服务——HTTP 客户端、重试、429 处理和密钥注入。
src/services/canvas-bridge	DataCanvas 适配器——表命名、TTL／来源跟踪和 SQL gate 扩展项。
tests/	与 src/ 结构对应的单元测试和集成测试。
docs/	设计和规划文档。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简要概括如下：

• 处理程序抛出异常，由框架捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围的日志，使用 ctx.state 存储租户范围的数据
• 在 src/mcp-server/tools/definitions/index.ts 中注册新工具
• 封装 FRED API 调用：验证原始响应 → 规范化为领域类型 → 返回输出架构；绝不伪造缺失字段

贡献

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

bun run devcheck
bun run test

许可证

Apache-2.0 — 详情请参阅 LICENSE。