Federal Reserve Economic Data MCP Server

美联储经济数据 MCP 服务

重要

免责声明：此开源项目与美联储或圣路易斯联邦储备银行无任何关联，也未获得其赞助或认可。“FRED”是圣路易斯联邦储备银行的注册商标，此处仅用于描述性目的。

一个模型上下文协议（MCP）服务，通过三个强大的工具，全面访问 800,000 多个美联储经济数据（FRED®）时间序列。

https://github.com/user-attachments/assets/66c7f3ad-7b0e-4930-b1c5-a675a7eb1e09

提示

如果您在研究或工作中使用了此项目，请使用 CITATION.cff 文件引用，或使用以下引用格式：

APA 格式：

Amorelli, S. (2025). Federal Reserve Economic Data MCP (Model Context Protocol) Server (Version 1.0.2) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.14536707

BibTeX：

@software{amorelli_2025_14536707,
  author       = {Amorelli, Stefano},
  title        = {{Federal Reserve Economic Data MCP (Model Context
                   Protocol) Server}},
  month        = jan,
  year         = 2025,
  publisher    = {Zenodo},
  version      = {1.0.2},
  doi          = {10.5281/zenodo.14536707},
  url          = {https://doi.org/10.5281/zenodo.14536707}
}

安装

手动安装

1. 克隆仓库：

   git clone https://github.com/stefanoamorelli/fred-mcp-server.git
   cd fred-mcp-server
   

2. 安装依赖项：

   pnpm install
   

3. 构建项目：

   pnpm build
   

配置

此服务需要 FRED® API 密钥。您可以从 FRED® 网站获取密钥。

例如，在 Claude Desktop 上安装服务，然后修改 claude_desktop_config.json 文件并添加以下配置：

{
  "mcpServers": {
    "FRED MCP Server": {
      "command": "/usr/bin/node",
      "args": [
        "<PATH_TO_YOUR_CLONED_REPO>/fred-mcp-server/build/index.js"
      ],
      "env": {
        "FRED_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

使用 Docker

您也可以使用 Docker 运行 FRED MCP 服务。将此配置添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "fred-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "FRED_API_KEY=<your-key-here>",
        "stefanoamorelli/fred-mcp-server:latest"
      ],
      "env": {}
    }
  }
}

将 <your-key-here> 替换为您实际的 FRED API 密钥。

使用 Streamable HTTP 传输

对于网络部署，您可以使用 Streamable HTTP 传输而非 stdio 运行服务：

# Using CLI flag
node build/index.js --http

# Or using environment variable
TRANSPORT=http node build/index.js

# Custom port (default is 3000)
PORT=8080 node build/index.js --http

服务将在 http://localhost:3000/mcp（或您自定义的端口）上提供。

客户端请求示例：

# Initialize session
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0.0"}}}'

# Use the mcp-session-id from the response header for subsequent requests
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session-id-from-init>" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

GET /healthz 端点会报告活跃会话、缓存统计信息和运行时间，供负载均衡器和编排器使用。

配置

所有设置均为环境变量，并设有合理的默认值：

变量	默认值	描述
FRED_API_KEY	(required)	您的 FRED API 密钥
FRED_API_TIMEOUT_MS	30000	对 FRED API 的单次请求超时时间
FRED_API_MAX_RETRIES	3	针对 429/5xx/网络故障的重试次数（采用带抖动的指数退避，并遵循 Retry-After）
FRED_API_RETRY_BASE_DELAY_MS	500	重试退避的基础延迟
FRED_RATE_LIMIT_PER_MINUTE	120	客户端令牌桶速率限制，与 FRED 的每个密钥配额一致
FRED_CACHE_TTL_MS	60000	API 响应缓存的 TTL（0 表示禁用缓存）
FRED_CACHE_MAX_ENTRIES	500	LRU 缓存容量
TRANSPORT	stdio	设置为 http 以使用 Streamable HTTP 传输
HOST	(all interfaces)	HTTP 绑定地址
PORT	3000	HTTP 端口
MCP_MAX_SESSIONS	100	MCP 会话的最大并发数（超过此限制时，新会话会收到 503）
MCP_SESSION_TTL_MS	1800000	会话闲置多久后会被清理
MCP_SESSION_SWEEP_INTERVAL_MS	60000	闲置会话清理器的运行间隔
MCP_BODY_LIMIT	1mb	接受的 JSON 请求体大小上限
LOG_LEVEL	info	error、warn、info 或 debug（日志输出到 stderr）

相同的并发请求会合并为一次上游调用，成功的响应会被缓存，因此多个会话可以高效地共享同一个速率限制额度。

可用工具

此 MCP 服务提供三个功能全面的工具，用于访问全部 800,000 多个 FRED® 经济数据序列：

fred_browse

描述：通过类别、发布内容或数据来源浏览 FRED 的完整目录。

参数：

• browse_type（必填）：浏览类型——"categories"、"releases"、"sources"、"category_series"、"release_series"
• category_id（可选）：用于浏览某个类别下的子类别或序列的类别 ID
• release_id（可选）：用于浏览某个发布内容下序列的发布 ID
• limit（可选）：结果数量上限（默认值：50）
• offset（可选）：分页时要跳过的结果数量
• order_by（可选）：结果排序字段
• sort_order（可选）："asc" 或 "desc"

fred_search

描述：按关键词、标签或筛选条件搜索 FRED 经济数据序列。

参数：

• search_text（可选）：在序列标题和描述中搜索的文本
• search_type（可选）："full_text" 或 "series_id"
• tag_names（可选）：用于筛选的逗号分隔标签名称列表
• exclude_tag_names（可选）：要排除的逗号分隔标签名称列表
• limit（可选）：结果数量上限（默认值：25）
• offset（可选）：分页时要跳过的结果数量
• order_by（可选）：排序字段（例如 "popularity"、"last_updated"）
• sort_order（可选）："asc" 或 "desc"
• filter_variable（可选）：按 "frequency"、"units" 或 "seasonal_adjustment" 筛选
• filter_value（可选）：用于筛选该变量的值

fred_get_series

描述：通过序列 ID 获取任意 FRED 序列的数据，并支持数据转换和日期范围。

参数：

• series_id（必填）：FRED 序列 ID（例如，“GDP”、“UNRATE”、“CPIAUCSL”）
• observation_start（可选）：开始日期，格式为 YYYY-MM-DD
• observation_end（可选）：结束日期，格式为 YYYY-MM-DD
• limit（可选）：观测值的最大数量
• offset（可选）：要跳过的观测值数量
• sort_order（可选）：“asc” 或 “desc”
• units（可选）：数据转换：
  • “lin”（水平值／不转换）
  • “chg”（与上一期相比的变化）
  • “ch1”（与一年前相比的变化）
  • “pch”（百分比变化）
  • “pc1”（与一年前相比的百分比变化）
  • “pca”（复合年变化率）
  • “cch”（连续复合变化率）
  • “log”（自然对数）
• frequency（可选）：频率汇总（“d”、“w”、“m”、“q”、“a”）
• aggregation_method（可选）：“avg”（平均值）、“sum” 或 “eop”（期末值）

使用示例

使用这三个工具，你可以：

• 浏览所有经济类别并发现可用数据
• 按关键词或标签搜索特定指标
• 通过自定义转换获取 800,000 多个序列中的任意一个
• 获取 GDP、失业率、通胀、利率等实时经济数据

社交媒体鸣谢 📣

说明

想要获得展示机会？在介绍 FRED MCP Server 使用体验的帖子中，于 LinkedIn 上标记 Stefano Amorelli，或在 X 上标记 @stefanoamorelli，也可以提交 PR添加你的鸣谢内容！

感谢社区的支持！以下是一些热心人士的提及：

Scott G - “Claude 让我‘理解’其可能性的一个突破性时刻，就是这个 fred-mcp-server 项目……”

Scott G - 金融科技与数据分析专业人士 | LinkedIn 个人资料

John Shelburne - “FRED MCP Server 为金融分析带来了变革……”

John Shelburne - 拥有 20 多年经验的固定收益金融科技领军人物 | 机器学习与云计算专家 | LinkedIn 个人资料

测试

更多详情请参阅 TESTING.md。

# Run all tests
pnpm test

# Run specific tests
pnpm test:registry

许可证 ⚖️

这个开源项目采用 GNU Affero 通用公共许可证 v3.0（AGPL-3.0）授权。这意味着：

• 你可以使用、修改和分发此软件
• 如果你修改并分发此软件，必须依据 AGPL-3.0 发布你的更改
• 如果你在服务器上运行修改后的版本，必须向用户提供源代码
• 完整详情请参阅 LICENSE 文件

如需了解商业授权选项或咨询其他许可事宜，请联系 [email protected]。

© 2025 Stefano Amorelli