MCP-FREDAPI

MCP-FREDAPI

通过模型上下文协议（MCP）集成 FRED（美国联邦储备经济数据）API

目录

• 简介
• 安装
• 配置
  • FRED API 密钥
  • Claude/Cursor 配置
• 可用工具
• 参数
• 示例
  • 常见经济序列 ID
• 贡献
• 许可证
• 参考资料

简介

MCP-FREDAPI 通过模型上下文协议提供对圣路易斯联邦储备银行（FRED）经济数据的访问。与 Cursor 或其他兼容 MCP 的环境搭配使用时，此集成可让 Claude 等 AI 助手直接检索经济时间序列数据。

此软件包集成了 FRED 官方 API，尤其侧重于 series_observations endpoint，该端点提供经济指标的时间序列数据。

安装

有两种安装方式：

方法 1：使用 pip

安装所需依赖项：

pip install "mcp[cli]" httpx python-dotenv

克隆此代码库：

git clone https://github.com/Jaldekoa/mcp-fredapi.git
cd mcp-fredapi

方法 2：使用 uv（推荐）

推荐使用此方法，因为它与 mcp.json 中显示的配置一致。

1. 首先，如果尚未安装 uv，请安装：

pip install uv

2. 克隆此代码库：

git clone https://github.com/Jaldekoa/mcp-fredapi.git
cd mcp-fredapi

3. 使用 uv 运行服务（无需单独安装依赖项）：

uv run --with mcp --with httpx mcp run server.py

配置

FRED API 密钥

你需要一个 FRED API 密钥，可从 FRED API 获取。

在项目根目录中创建一个 .env 文件：

FRED_API_KEY=your_api_key_here

Claude/Cursor 配置

要配置 Cursor 使用此 MCP 服务，请将以下内容添加到 ~/.cursor/mcp.json 文件中：

{
  "mcpServers": {
    "mcp-fredapi": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-fredapi", "run", "--with", "mcp", "--with", "httpx", "mcp", "run", "server.py"]
    }
  }
}

将 /path/to/mcp-fredapi 替换为系统上代码库的实际路径。例如：

{
  "mcpServers": {
    "mcp-fredapi": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-fredapi", "run", "--with", "mcp", "--with", "httpx", "mcp", "run", "server.py"]
    }
  }
}

注意：在 Windows 上，路径中可以使用正斜杠 / 或双反斜杠 \\。

可用工具

get_fred_series_observations

从 FRED 检索经济时间序列观测值。

在 Cursor 中使用 Claude 时，可以直接通过以下方式调用此工具：

@mcp-fredapi:get_fred_series_observations

参数

get_fred_series_observations 工具接受以下参数。有关每个参数的完整技术详情，请参阅 FRED API 官方文档。

参数	类型	描述	允许的值	默认值	状态
series_id	str	经济序列的 ID	-	（必填）	✅ 可用
sort_order	str	观测值的排序顺序	'asc', 'desc'	'asc'	✅ 可用
units	str	数据值转换方式	'lin', 'chg', 'ch1', 'pch', 'pc1', 'pca', 'cch', 'cca', 'log'	'lin'	✅ 可用
frequency	str	观测值的频率	'd', 'w', 'bw', 'm', 'q', 'sa', 'a', 'wef', 'weth', 'wew', 'wetu', 'wem', 'wesu', 'wesa', 'bwew', 'bwem'	None	✅ 可用
aggregation_method	str	频率的聚合方法	'avg', 'sum', 'eop'	'avg'	✅ 可用
output_type	int	观测值的输出类型	1, 2, 3, 4	1	✅ 可用
realtime_start	str	实时期间的开始日期（YYYY-MM-DD）	-	None	❌ 不可用
realtime_end	str	实时期间的结束日期（YYYY-MM-DD）	-	None	❌ 不可用
limit	int/str	要返回的观测值的最大数量	介于 1 和 100000 之间	10	❌ 不可用
offset	int/str	从开头开始跳过的观测值数量	-	0	❌ 不可用
observation_start	str	观测值的开始日期（YYYY-MM-DD）	-	None	❌ 不可用
observation_end	str	观测值的结束日期（YYYY-MM-DD）	-	None	❌ 不可用
vintage_dates	str	以逗号分隔的版本日期列表	-	None	❌ 不可用

警告

由于当前 MCP 实现存在限制，只有部分参数可以正常工作：

• ✅ 可用参数：series_id、sort_order、units、frequency、aggregation_method 和 output_type。
• ❌ 不可用参数：realtime_start、realtime_end、limit、offset、observation_start、observation_end 和 vintage_dates。

为获得最佳效果，请在查询中使用可用参数。未来的更新可能会解决这些限制。

示例

获取美国 GDP 数据

在 Cursor 中使用 Claude 时，可以这样请求 GDP 数据：

Can you get the latest GDP data from FRED?

@mcp-fredapi:get_fred_series_observations
{
  "series_id": "GDP"
}

按降序获取 GDP 数据

Can you get the GDP data in descending order (newest first)?

@mcp-fredapi:get_fred_series_observations
{
  "series_id": "GDP",
  "sort_order": "desc"
}

获取年度 GDP 数据

Can you get annual GDP data?

@mcp-fredapi:get_fred_series_observations
{
  "series_id": "GDP",
  "frequency": "a"
}

获取通胀率

要获取消费者价格指数数据及其百分比变化：

What's the recent inflation rate in the US?

@mcp-fredapi:get_fred_series_observations
{
  "series_id": "CPIAUCSL",
  "units": "pch",
  "frequency": "m"
}

不同的输出格式

Show me GDP data in a different format.

@mcp-fredapi:get_fred_series_observations
{
  "series_id": "GDP",
  "output_type": 2
}

贡献

欢迎贡献。请按照以下步骤操作：

1. Fork 仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 进行更改
4. 提交更改（git commit -m 'Add an amazing feature'）
5. 推送到分支（git push origin feature/amazing-feature）
6. 创建 Pull Request

许可证

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

参考资料

• FRED API 文档 - 序列观测值 - 本项目所用 FRED API 端点的官方文档。
• FRED API - 关于如何获取 API 密钥以及 API 的一般文档。
• Model Context Protocol - Model Context Protocol 文档。