US Macro

US-Macro-MCP

一个 MCP 服务，让 AI 助手能够便捷地获取美国宏观经济数据——涵盖通胀、就业、增长、住房、消费者行为、利率、金融压力、市场和联邦财政等领域的 58 项指标，数据来源于美联储的 FRED 数据库。

该服务经过设计，让助手无需了解 FRED 序列 ID，也无需自行计算。查询 cpi，即可获得最新读数、前一期读数、一年前的读数，以及已计算好的百分比变化。

注册表官方链接： https://pypi.org/project/us-macro-mcp/

更新日志

日期	版本	说明
2026-07-27	0.1.2	添加 OS 和 Python 版本分类器、更新日志，并将联系地址改为 GitHub noreply。
2026-07-27	0.1.1	添加用于验证注册表所有权的 mcp-name 标记。首个列入官方 MCP 注册表的版本。
2026-07-27	0.1.0	首次发布——58 项指标、8 个工具。已撤回，由 0.1.1 取代。

功能

工具	用途
list_indicators	按类别查看所有可用指标
get_indicator	获取某项指标的当前读数及其变化
get_history	获取完整时间序列，用于分析趋势和绘制图表
compare_indicators	在相同时间范围内获取两项或更多指标，并进行标准化以便比较
release_calendar	查看未来几天计划发布的经济报告
macro_snapshot	一次调用即可查看整体经济状况或某个类别的情况
recession_signals	查看萨姆规则、收益率曲线、信用利差、申领人数和金融状况，并查看各项评级
search_indicators	不知道指标名称时，通过关键词查找指标

要求

一个免费的 FRED API 密钥。请访问 fredaccount.stlouisfed.org/apikeys 申请——大约需要一分钟，而且完全免费。

安装

Codex 插件市场

安装 uv，并确保 Codex 可以在 PATH 中找到 uvx。该插件会在本地通过 stdio 启动已发布的 PyPI 版本 us-macro-mcp==0.1.2；它需要 Python 3.10 或更高版本。由于此版本使用 SDK 的 v1 FastMCP API，其启动器会将 MCP SDK 版本限制为 >=1.2,<2。

1. 启动 Codex 应用前，请确保该应用可以访问你的 FRED_API_KEY 环境变量。插件会将此变量传递给 MCP 服务；它不会将密钥存储在文件中，也不会在安装时提示你输入密钥。 在 macOS 上，在本地运行以下命令，然后完全退出并重新打开 Codex：

   launchctl setenv FRED_API_KEY 'YOUR_FRED_API_KEY'
   

   将占位符替换为你自己的密钥。不要提交或分享密钥。launchctl setenv 仅对当前登录会话生效；重新登录后需要再次运行。在 Linux 上，从终端启动 Codex 前先导出该变量；在 Windows 上，设置用户环境变量并重启 Codex。

2. 在 Codex 中，打开 Plugins → Add → Add plugin marketplace。

3. 将 Source 设为 Signal-Drifts/US-Macro-MCP（或 https://github.com/Signal-Drifts/US-Macro-MCP.git），将 Git ref 设为 main， Sparse paths 留空，然后点击 Add marketplace。

4. 选择 Signal Drifts 并安装 US Macro，然后开始新的聊天。

5. 试着说：“使用 US Macro 列出可用的指标”，然后请求宏观快照。列出指标可用于检查发现功能；获取实时数据还需要 FRED 密钥和访问 FRED 的网络连接。

你也可以使用 Codex CLI 注册该市场：

codex plugin marketplace add Signal-Drifts/US-Macro-MCP --ref main

目录位于 .agents/plugins/marketplace.json；插件清单和 MCP 配置位于 plugins/us-macro-mcp/ 下。插件包有自己的版本号：插件 0.1.4 使用 PyPI 服务端 0.1.2。更新服务端版本时，请更新插件 .mcp.json 中固定的 PyPI 版本，并提升插件清单中的版本号，然后刷新市场和已安装的插件。

此仓库提供的是自定义市场。加入 OpenAI 的公开插件目录需要经过单独的提交和审核流程；目前，本地 MCP 提交需要获得批准的合作伙伴组织。请参阅官方的 插件打包指南 和 仅限桌面端的提交指南。

现有的 MCP Registry 标识符 io.github.hgus107/us-macro-mcp 会保留； 迁移 GitHub 仓库不会迁移该 Registry 身份。未来 Python/MCP Registry 版本中的仓库链接会指向 Signal-Drifts；已发布在 PyPI 上的元数据仍与其现有版本关联。

Claude Desktop

将以下内容添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "us-macro": {
      "command": "uvx",
      "args": ["--from", "us-macro-mcp==0.1.2", "--with", "mcp[cli]>=1.2,<2", "us-macro-mcp"],
      "env": { "FRED_API_KEY": "your_key_here" }
    }
  }
}

Claude Code

claude mcp add us-macro --env FRED_API_KEY=your_key_here -- uvx --from us-macro-mcp==0.1.2 --with 'mcp[cli]>=1.2,<2' us-macro-mcp

其他任何 MCP 客户端

设置好 FRED_API_KEY 环境变量后，运行：

uvx --from us-macro-mcp==0.1.2 --with 'mcp[cli]>=1.2,<2' us-macro-mcp

该服务通过 stdio 使用 MCP 通信。

工作方式

它在本地运行。 没有任何内容托管在远程。你的客户端会在自己的机器上将该服务作为子进程启动，并使用你自己的 API 密钥。除了向 FRED 发出的只读请求外，没有数据会离开你的计算机。

它会缓存。 单次 macro_snapshot 会一次性获取 19 个指标，而且对话中往往会反复请求相同的数据序列。答案会在内存中保留一段时间，时长与数据实际可能发生变化的频率相匹配：像美国国债收益率这样的日度数据序列缓存一小时，像 CPI 这样的月度数据序列缓存半天。进程退出时会丢弃缓存。如果你想调整缓存行为，请修改 fred.py 中的 CACHE_SECONDS。

它绝不会记录你的 API 密钥。 请求日志仅记录端点、数据序列和状态码；任何错误文本都会先移除密钥，再写入日志或返回。

已知限制

• ISM Manufacturing 和 Services PMI 不可用。 ISM 对其数据进行商业授权，并已从 FRED 撤下。Conference Board Consumer Confidence Index 也同样如此。两者都没有免费的数据来源。
• 利率是全国平均值，而非各家银行的利率。 30 年期抵押贷款利率是 Freddie Mac 对数千家贷款机构进行的每周调查结果，并非任何特定银行公布的利率。没有任何机构免费发布各家机构的利率。
• 不包含 FOMC 会议日期。 FRED 发布的是数据公布日程，而非美联储的会议日历。
• Michigan 消费者信心数据存在滞后。 截至本文撰写时，FRED 的 UMCSENT 和 MICH 系列比其他月度指标晚约两个月。latest_date 字段会始终告知你实际获取到的数据日期。
• 数据按其所覆盖的期间标注。 6 月 CPI 的日期为 2026-06-01，并于 7 月中旬公布。请务必查看 latest_date，不要假设最近一个月的数据已经公布。

数据来源与免责声明

所有数据均来自 FRED，由圣路易斯联邦储备银行维护，并汇总自劳工统计局、经济分析局、人口普查局、美联储理事会等机构。

recession_signals 工具将广为人知的统计阈值应用于公开数据。它并非预测，本服务返回的任何内容都不构成投资建议。

年度维护清单

美联储会提前约两年公布会议日程，而 Python、MCP SDK 和 FRED 自身的目录每年都会发生变化。请每年一月逐项完成此清单，并发布新版本。

数据

• 从 federalreserve.gov/monetarypolicy/fomccalendars.htm 更新 src/us_macro_mcp/fomc.py 中的 FOMC 日程，并将 VALID_THROUGH 向后延长。日程列表用尽后，next_fomc_meeting 字段将为空。

• 重新验证目录中的每个序列 ID。FRED 会在不另行通知的情况下停用序列——ADP 就业序列就是如此被停用的，它返回有效响应，但观测值为零：

  cd ~/Downloads/Apps/US-Macro-MCP && uv run python -c "
  import asyncio, logging
  logging.getLogger('us_macro_mcp').setLevel(logging.WARNING)
  from us_macro_mcp import catalog, fred
  async def main():
      sem = asyncio.Semaphore(8)
      async def check(i):
          async with sem:
              try:
                  p = await fred.get_observations(i.series_id, start='2025-01-01', frequency_hint=i.frequency)
                  return (i.name, 'OK' if p else 'EMPTY', p[-1]['date'] if p else '-')
              except Exception as e:
                  return (i.name, 'FAIL: ' + str(e)[:70], '-')
      rows = await asyncio.gather(*(check(i) for i in catalog.CATALOG))
      print('problems:', [r for r in rows if r[1] != 'OK'])
  asyncio.run(main())
  "
  

• 检查之前无法免费获取的数据现在是否已免费开放，尤其是目前不在 FRED 中的 ISM PMI 和 Conference Board 消费者信心指数。

• 检查 FRED API 条款和速率限制（目前每个密钥每分钟 120 次请求）是否有变化。

依赖项

• 升级 mcp SDK，并阅读其变更日志，检查是否有不兼容变更。FastMCP 属于官方 SDK，因此其中的主版本升级可能会改变工具的声明方式或服务的启动方式。
• 检查 MCP 规范是否修订了其传输机制或工具架构。
• 升级 httpx。
• 检查 requires-python。移除已结束生命周期的版本，并确认当前最低版本仍可正常安装。

发布

• 运行完整测试套件：全部八个工具，以及负面和边界情况。
• 更新 pyproject.toml 和 server.json 中的版本号。两者必须一致，否则注册表会拒绝发布。
• 运行 uv build 和 uv publish 发布到 PyPI。
• 运行 mcp-publisher publish 发布到官方 MCP 注册表。
• 在 GitHub 上为此版本打标签。

许可证

MIT

支持与政策

• 支持与错误报告
• 隐私政策
• 软件与数据条款