MCP-FREDAPI

FRED (Federal Reserve Economic Data) API 与 Model Context Protocol (MCP) 的集成

目录

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

介绍

MCP-FREDAPI 通过 Model Context Protocol 提供对圣路易斯联邦储备银行 (FRED) 经济数据的访问。这种集成允许像 Claude 这样的 AI 助手在与 Cursor 或其他 MCP 兼容环境中使用时直接检索经济时间序列数据。

此包与 官方 FRED API 集成，特别关注提供经济指标时间序列数据的 series_observations 端点。

安装

有两种安装方法：

方法 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

1. 克隆此仓库：

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

1. 使用 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'	无	✅ 可用
aggregation_method	str	频率聚合方法	'avg', 'sum', 'eop'	'avg'	✅ 可用
output_type	int	观测输出类型	1, 2, 3, 4	1	✅ 可用
realtime_start	str	实时周期开始日期 (YYYY-MM-DD)	-	无	❌ 不可用
realtime_end	str	实时周期结束日期 (YYYY-MM-DD)	-	无	❌ 不可用
limit	int/str	返回的最大观测数量	在1到100000之间	10	❌ 不可用
offset	int/str	从开始处跳过的观测数量	-	0	❌ 不可用
observation_start	str	观测开始日期 (YYYY-MM-DD)	-	无	❌ 不可用
observation_end	str	观测结束日期 (YYYY-MM-DD)	-	无	❌ 不可用
vintage_dates	str	逗号分隔的版本日期列表	-	无	❌ 不可用

[!WARNING] 关于参数兼容性的注意事项

由于当前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. 分叉仓库
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 文档的信息。
• 模型上下文协议 - 模型上下文协议的文档。