A Swedish Monetary‑Policy Data MCP Server

瑞典货币政策数据 MCP 服务

SwemoMCO 是一个非官方的货币政策数据 MCP 服务，它将 Sveriges Riksbank 的开放 API 封装为 Model‑Context‑Protocol（MCP）微服务。它将原始 REST 端点转换为类型化的 Python 工具，大模型可以调用这些工具，人类也可以通过任意 MCP 客户端使用这些工具。

本版 README 假定你使用 Astral 的 uv 管理依赖并执行程序。

---

目录

1. 项目缘起
2. 底层数据
   • 政策轮次
   • 序列标识符
   • 预测版本与观测值
3. MCP 服务的工作方式
   • 架构
   • 工具目录
4. 安装
5. 快速开始
6. 示例（分析师与记者）
7. Docker
8. 开发
9. 许可证

---

项目缘起

处理货币政策数据可能很复杂：原始 API 需要手动编写查询，还需要了解不同的数据序列。 本项目：

• 将 HTTP 调用封装在简洁的异步 Python 接口之后，
• 将每个序列公开为大模型可发现的 MCP 工具，让 Claude Desktop 和其他 MCP 客户端工具能够按需获取瑞典宏观经济数据。

自 2020 年起，Riksbank 的服务除了预测值，还会在官方数据发布后提供实际（观测）数据。因此，该数据集适用于历史分析（例如：“2022 年的通胀实际如何变化？”），也适用于预测查询（例如：“Riksbank 预计明年 GDP 会如何变化？”）。

---

底层数据

政策轮次

Riksbank 每年发布四到五次新一轮预测。 每次发布均以 YYYY:I 标记（例如，2025:2 表示 2025 年的第二次发布）。

序列标识符

每个时间序列名称都遵循以下模式：

COUNTRY‑FREQUENCY‑AREA‑DECOMPOSITION‑UNIT‑ADJUSTED

示例：SEQGDPNAYCA → 瑞典（SE）、季度（Q）、GDP（GDP）、国民账户分解（NA）、同比变化（Y）、日历调整（CA）。使用以下命令发现数据目录：

GET /forecasts/series_ids

预测版本与观测值

每个政策轮次都会产生一版关键宏观经济变量预测。同时，随着实际结果数据的发布，Riksbank 也会更新其实际观测值。这意味着你可以：

• 固定某个政策轮次（例如 "2024:1"），只查看该轮次的预测，以及截至该轮次可获取的观测值。
• 使用 "latest" 获取所有历史观测值（即截至目前已知的最终实际值），以及最新的预测版本。这非常适合历史分析，尤其是在你想查看最终修订值或实际值，而非较早的预测时。

预测元数据示例：

{
  "revision_dtm": "2024‑07‑02T08:55:00Z",
  "forecast_cutoff_date": "2024‑06‑18",
  "policy_round": "2024:3",
  "policy_round_end_dtm": "2024‑07‑02T09:30:00Z"
}

---

MCP 服务的工作方式

架构

┌─────────────────────────────────────────────────────────┐
│  FastMCP Server (src/swemo_mcp/server.py)               │
│                                                         │
│  • registers ≈30 *tools* (one per economic series)      │
│  • exposes them on stdio / SSE / HTTP                   │
└───────────────▲──────────────────────────────▲──────────┘
                │                              │
         async httpx                     LLM / user
                │                              │
┌───────────────┴────────────┐        ┌────────┴──────────┐
│ Riksbank REST API          │        │ mcp‑cli / ChatGPT │
└────────────────────────────┘        └───────────────────┘

• services/monetary_policy_api.py – 轻量级异步封装，支持自动指数退避（HTTP 429 时进行最大次数的重试）。
• tools/monetary_policy_tools.py – 每个序列对应一个声明式函数；文档字符串同时用作大模型提示词。
• models.py 中的 Pydantic v2 模型确保每个响应都符合预期的架构。

工具目录

工具	系列 ID	描述
get_gdp_data	SEQGDPNAYCA	GDP 同比，日历调整后
get_unemployment_data	SEQLABUEASA	劳动力调查失业率
get_cpi_data	SEMCPINAYNA	总体 CPI 同比
…	…	总计约 30 个系列——运行 list_series_ids() 查看完整列表。

每个工具的签名如下：

async def get_<series>_data(policy_round: str | None = None) -> MonetaryPolicyDataResponse

传入 policy_round="2024:3" 可固定数据版本；省略则使用完整历史数据。对于最终历史数据，传入 policy_round="latest"，让工具合并所有已实现（观测到）的数据点。

---

安装

先决条件：

• Python ≥ 3.12（使用 typing.TypeAlias/PEP 604 联合类型）
• Astral uv ≥ 0.2.0

运行一条命令即可克隆并设置项目：

uv sync

uv sync 会安装 pyproject.toml 中声明的所有生产和开发依赖项；如有需要，还会创建虚拟环境，并锁定确切版本，确保每位贡献者或 CI 流水线使用相同的技术栈。

---

Claude Desktop 集成

编辑 claude_desktop_config.json，添加 Kolada MCP Server：

Docker 镜像（本地构建）

"SwemoMCP": {
  "args": [
    "run",
    "-i",
    "--rm",
    "--name",
    "swemo-mcp-managed",
    "swemo-mcp:local"
  ],
  "command": "docker",
  "env": {}
}

通过 PyPI 获取预构建容器

"SwemoPyPI": {
  "args": ["swemo-mcp"],
  "command": "/Users/hugi/.cargo/bin/uvx"
}

本地 UV 执行（不使用 Docker）

将 [path to kolada-mcp] 替换为本地目录：

"SwemoLocal": {
  "args": [
    "--directory",
    "[path to kolada-mcp]/src/kolada_mcp",
    "run",
    "kolada-mcp"
  ],
  "command": "uv"
}

更新后重启 Claude Desktop。

用作库

import asyncio
from swemo_mcp.tools import get_policy_rate_data

async def main():
    from swemo_mcp.query import ForecastRequest
    req = ForecastRequest(policy_round="2023:4", include_realised=True)
    data = await get_policy_rate_data(req)
    print(data.vintages[0].observations[:5])  # first 5 observations

asyncio.run(main())

由于所有内容都采用类型标注且为异步，你可以将这些工具直接集成到笔记本、仪表板或其他服务中。

---

Docker

该项目附带一个多阶段 Dockerfile，最终层使用 uv，因此容器构建可受益于确定性的依赖解析。

docker build -t swemo-mcp:latest .

docker run -i --rm swemo-mcp:latest | mcp chat

如果你更倾向于在开发中使用 Docker Compose，示例 compose.yaml 展示了如何挂载源代码目录并热重载更改。

---

开发

1. 设置环境：

   uv sync --dev
   

2. 以开发模式运行服务器并启用实时重载（需要 mcp dev）：

   uv run mcp dev src/swemo_mcp/server.py
   

3. 打开 MCP Inspector 进行测试和调试：

   http://localhost:5173

4. 运行测试套件（pytest + asyncio）：

   uv run pytest -q
   

5. 使用 Ruff 自动格式化和检查代码：

   uv run ruff check . --fix
   

---

许可证

采用 Apache 2.0 许可证。完整文本请参阅 LICENSE。

---

免责声明

• 这是一个用于获取瑞典央行数据的非官方 MCP 服务。底层 API 可能会发生变化，本项目可能无法始终反映最新更新。
• 瑞典央行未参与本项目的开发。数据按“原样”提供，不提供任何形式的保证。
• 瑞典央行的数据受其自身使用条款约束。更多信息请参阅瑞典央行 API 门户。