A Swedish Monetary‑Policy Data MCP Server

スウェーデンの金融政策データ MCP サーバー

SwemoMCO は、Sveriges Riksbank のオープン API を Model-Context-Protocol（MCP）マイクロサービスでラップする、非公式の金融政策データ MCP サーバーです。生の REST エンドポイントを、LLM や任意の MCP クライアントを通じて人間が呼び出せる型付き Python ツールに変換します。

この README の版では、依存関係の管理と実行に Astral の uv を使用することを前提としています。

---

目次

1. このプロジェクトの目的
2. 基盤となるデータ
   • 政策ラウンド
   • 系列識別子
   • 予測ビンテージと観測値
3. MCP サーバーの仕組み
   • アーキテクチャ
   • ツール一覧
4. インストール
5. クイックスタート
6. 使用例（アナリストとジャーナリスト向け）
7. Docker
8. 開発
9. ライセンス

---

このプロジェクトの目的

金融政策データの扱いは複雑になりがちです。生の API を使うには、クエリを手作業で作成し、さまざまな系列について知っている必要があります。 このプロジェクトは、次のことを行います。

• HTTP 通信の処理を、すっきりとした非同期 Python インターフェースの背後に隠します。
• すべての系列を、LLM が検出できるMCP ツールとして公開します。これにより、Claude Desktop やその他の MCP クライアントツールが、必要に応じてスウェーデンのマクロ経済データを取得できます。

2020 年以降、Riksbank のサービスには、公式統計の公表後に予測値と実績（観測）データの両方が含まれるようになりました。そのため、このデータセットは過去の分析（例：「2022 年のインフレ率は実際にどう推移しましたか？」）や、予測の照会（例：「Riksbank は来年の GDP をどのように予測していますか？」）に適しています。

---

基盤となるデータ

政策ラウンド

Riksbank は、年に 4～5 回、新しい予測一式を公表します。各公表には YYYY:I というラベルが付けられます（例：2025 年の 2 回目の公表を示す 2025:2）。

系列識別子

すべての時系列名は、次のパターンに従います。

COUNTRY‑FREQUENCY‑AREA‑DECOMPOSITION‑UNIT‑ADJUSTED

例：SEQGDPNAYCA → スウェーデン（SE）、四半期（Q）、GDP（GDP）、国民経済計算の内訳（NA）、前年比（y/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 – 系列ごとに宣言的な関数を 1 つ用意しています。docstring は LLM 向けプロンプトも兼ねています。
• models.py の Pydantic v2 モデルにより、すべての応答が想定されるスキーマに準拠していることを保証します。

ツール一覧

ツール	シリーズ ID	説明
get_gdp_data	SEQGDPNAYCA	GDP 前年比、暦調整済み
get_unemployment_data	SEQLABUEASA	LFS 失業率
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

このプロジェクトには、最終レイヤーで uv を使用するマルチステージ Dockerfile が含まれているため、コンテナのビルドで決定論的な依存関係解決を利用できます。

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 を参照してください。

---

免責事項

• これは、Riksbank のデータを扱う非公式の MCP サーバーです。基盤となる API は変更される場合があり、このプロジェクトには常に最新の更新が反映されるとは限りません。
• Sveriges Riksbank は、このプロジェクトの開発に一切関与していません。データは、いかなる種類の保証もなく「現状有姿」で提供されます。
• Riksbank のデータには、独自の利用規約が適用されます。詳細については、Riksbank の API ポータルを参照してください。