📊 Statistics Canada API MCP Server

Statistics Canada MCP サーバー

Statistics Canada の Web Data Service（WDS）および SDMX REST API 用の MCP サーバーと CLI です。Claude、Cursor、VS Code Copilot、Gemini など、あらゆる MCP クライアントからカナダの統計データに構造化された方法でアクセスできます。LLM を使わずに直接ダウンロードできる、単独で動作する statcan CLI も含まれています。

Render でホストされています。ほとんどのユーザーはインストール不要です。クイックスタートをご覧ください。

⚠️ LLM はデータを捏造することがあります。重要な数値は必ずStatistics Canada の公式情報源で確認してください。

---

目次

• クイックスタート
• 使用例
• クライアント別のセットアップ
• Claude.ai によるこのサーバーの使用方法
• MCP プロンプト
• statcan CLI
• 機能とツール
• プロジェクト構成
• 既知の問題
• 貢献者

---

クイックスタート

自分に合った方法を選んでください。オプション 1 では何もインストールする必要はありません。

オプション 1 — ホスト済みサーバーを使用する（推奨）

Render 上の公開サーバーに直接接続します。uv もターミナルもローカルでのセットアップも不要です。

Claude Desktop / Claude.ai

1. 設定 → コネクター → カスタムコネクターを追加を開きます
2. 名前：mcp-statcan
3. URL：https://mcp-statcan.com/mcp
4. 保存して再起動します

Claude Code

claude mcp add statcan --transport http https://mcp-statcan.com/mcp --scope global

ホスト済みサーバーでは、すべての WDS + SDMX ツールを利用できます。データベースツール（SQLite）を使うにはローカルでのセットアップ（オプション 3）が必要です。共有サーバーからは意図的に除外されています。

---

オプション 2 — HTTP でセルフホストする（WDS + SDMX、DB なし）

ホスト済みバージョンと同じツールを備えたローカルサーバーを実行します。

ステップ 1 — uvをインストールします：

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

ステップ 2 — サーバーを起動します：

uvx statcan-mcp-server --transport http
# Listening at http://localhost:8000

ステップ 3 — クライアントを http://localhost:8000/mcp に接続します。

---

オプション 3 — ローカルで完全にセットアップする（WDS + SDMX + SQLite）

オプション 2 のすべてに加え、SQL でデータを保存・照会するためのデータベースツールも利用できます。stdio 経由で実行します。

ステップ 1 — uv をインストールします（上記と同じです）。

ステップ 2 — 以下のクライアント別のセットアップにある stdio 用の設定スニペットを使って、クライアントを設定します。

初回使用時に uvx がサーバーを自動的にダウンロードして実行します。

---

オプション 4 — statcan CLI（LLM 不要）

ターミナルから StatCan データを直接ダウンロードします。statcan CLIをご覧ください。

uvx statcan-mcp-server        # installs the package
statcan search "labour force"
statcan metadata 14-10-0287-01                                    # run first to find dimension IDs
statcan download 14-10-0287-01 --key "1.1.1" --last 12 --output lfs.csv  # run `statcan metadata <pid>` first to find real dimension IDs
statcan describe                                                  # machine-readable command reference for agents

---

使用例

チャットの例

データセット	クエリ	デモ	ソース
カナダの温室効果ガス排出量	"Create a simple visualization for greenhouse emissions for Canada as a whole over the last 4 years"	チャット	表 38-10-0097-01
カナダのサービスの国際貿易	"Create a quick analysis for international trade in services for the last 6 months with a visualization"	チャット	表 12-10-0144-01
オンタリオ州の建築建設価格指数	"Generate a visualization for Ontario's Building Price index from Q4 2023 to Q4 2024"	チャット	表 18-10-0289-01
カナダの失業ダッシュボード	"Create a Canadian Unemployment Dashboard using statcan mcp"	チャット	表 14-10-0287-01

ダッシュボードの例

タイトル	リンク	ソース
カナダの重要鉱物経済	ダッシュボード	表 36-10-0708-01
あらゆるものの価格：CPI ダッシュボード 2015–2026	ダッシュボード	表 18-10-0004-01
カナダのバイオ医療・バイオテクノロジー産業	ダッシュボード	表 27-10-0297-01

---

クライアント別のセットアップ

ホスト型サーバー（オプション 1）

Claude Desktop — Settings → Connectors → Add Custom Connector

• 名前：mcp-statcan
• URL：https://mcp-statcan.com/mcp

Claude Code

claude mcp add statcan --transport http https://mcp-statcan.com/mcp --scope global

Cursor — .cursor/mcp.json（プロジェクト）または ~/.cursor/mcp.json（グローバル）：

{
  "mcpServers": {
    "statcan": {
      "url": "https://mcp-statcan.com/mcp"
    }
  }
}

VS Code (GitHub Copilot) — .vscode/mcp.json：

{
  "servers": {
    "statcan": {
      "type": "http",
      "url": "https://mcp-statcan.com/mcp"
    }
  }
}

---

セルフホスト HTTP（オプション 2）

先に uvx statcan-mcp-server --transport http を起動してから、クライアントを設定してください。

ほとんどのクライアントでは、stdio と HTTP を橋渡しするために mcp-proxy が必要です。Claude Code はネイティブに接続できます。

Claude Desktop — Settings → Developer → Edit Config：

{
  "mcpServers": {
    "statcan": {
      "command": "uvx",
      "args": ["mcp-proxy", "--transport", "streamablehttp", "http://localhost:8000/mcp"]
    }
  }
}

Claude Code

claude mcp add statcan --transport http http://localhost:8000/mcp --scope global

Cursor / VS Code / Gemini — 同じ mcp-proxy ラッパーを使い、http://localhost:8000/mcp を指定します。

---

完全ローカル / stdio（オプション 3）

Claude Desktop — Settings → Developer → Edit Config：

{
  "mcpServers": {
    "statcan": {
      "command": "uvx",
      "args": ["statcan-mcp-server", "--db-path", "/Users/<you>/.statcan-mcp/statcan_data.db"]
    }
  }
}

--db-path には絶対パスを指定してください。Claude Desktop はサブプロセスの HOME 環境変数を上書きするため、デフォルトのパス解決に問題が生じることがあります。

Claude Code

claude mcp add statcan --scope global -- uvx statcan-mcp-server

Cursor / VS Code / Gemini — stdio コマンドとして uvx statcan-mcp-server を使用します。

---

Claude.ai がこのサーバーを使用する方法

Claude.ai（ウェブ）には bash サンドボックスがないため、シェルコマンドを実行できません。その代わりに、MCP ツールでデータを検索し、Python スクリプトツールでコンテキストウィンドウを肥大化させずにデータを取得します。

パターン：

1. MCP tools (small payloads — metadata only):
   search_cubes_by_title("labour force")  → productId
   get_sdmx_structure(productId=...)      → dimension layout + codes
   get_sdmx_key_for_dimension(...)        → OR key for large dimensions

2. Python script (data never enters context):
   url = "https://mcp-statcan.com/files/sdmx/<pid>/<key>?lastNObservations=12"
   → validate URL domain → write to ./statcan_<pid>.csv → print summary only

3. Follow-up script (analysis from local file):
   rows = list(csv.DictReader(open("./statcan_<pid>.csv")))
   → filter / sort / aggregate → print only the result

順位付け、比較、成長率などの計算が必要な質問では、query_sdmx がサーバー上で SQL を実行して答えだけを返すため、生の行データがコンテキストウィンドウに入ることはありません。

**Claude Code（bash サンドボックス）**では、代わりに statcan CLI を使用します。

statcan search "labour force"
statcan metadata 14-10-0287-01  # run first to find dimension IDs
statcan download 14-10-0287-01 --key "1.1.1" --last 12 --output ./lfs.csv  # run `statcan metadata <pid>` first to find real dimension IDs
awk -F',' 'NR>1 && $1=="Canada"' ./lfs.csv | sort -t',' -rn -k5 | head -10

---

MCP プロンプト

このサーバーには、対応クライアントでスラッシュコマンドとして利用できる5つのプロンプトが付属しています。それぞれに、Claude Code（bash）と Claude.ai ウェブ（Python スクリプト）向けの2種類の手順があります。

プロンプト	内容
/statcan-data-lookup	最初から最後までの手順：検索 → 構造の確認 → キーの作成 → ローカルファイルへの取得 → 分析
/sdmx-key-builder	SDMX キーの構文：ワイルドカード、OR キー、時間パラメーター、ダウンロード URL の形式
/statcan-download	特定のテーブルのダウンロード：CLI コマンドと Python スクリプトによる代替手段
/statcan-explore	実行前のサンプル確認：3期間の取得、列の配置、サイズの見積もり
/statcan-vector-pipeline	複数系列のダウンロードと系列間の比較

Claude Code での使用方法：

/statcan-data-lookup topic="consumer price index" analysis_goal="trend last 5 years"
/statcan-download product_id=18100004 last_n=24

---

statcan CLI

LLM を使わずに StatCan データをダウンロードできるスタンドアロン CLI です。パイプ処理に適した CSV／JSON を標準出力に出力し、進捗情報とエラーは標準エラー出力に出力します。

テーブルの探索（検索、メタデータの確認、ダウンロードの順）：

エージェントモード（--json エンベロープ、型付き終了コード、statcan describe）：

録画は、VHS を使って assets/tapes/ 内のスクリプトから生成されます：vhs assets/tapes/cli-agent.tape。

インストール：

pip install statcan-mcp-server   # or: uvx statcan-mcp-server (no install)

コマンド：

statcan search <term>            Search tables by keyword
statcan metadata <product-id>    Show table structure (dimensions + members)
statcan download <product-id>    Download observations via SDMX
statcan vector <vector-id>...    Download one or more vector series
statcan codeset                  Show StatCan code definitions (UOM, frequency, etc.)
statcan describe                 Commands, options, exit codes and JSON envelopes as JSON

一般的な使い方：

# Find a table
statcan search "consumer price index"
statcan search "labour force" --max-results 10 --format json

# Inspect structure before downloading
statcan metadata 18-10-0004-01
statcan metadata 18100004 --full        # show all dimension members

# Download data (run `statcan metadata <pid>` first to find real dimension IDs)
statcan download 18-10-0004-01 --key "1.1.1" --last 12 --output cpi.csv
statcan download 18-10-0004-01 --key "1.1.1" --start 2020-01 --end 2024-12
statcan download 18-10-0004-01 --key "1.1.1" --last 5 --dry-run   # preview SDMX URL

# Download by vector ID
statcan vector v41690973 --last 24 --output series.csv
statcan vector v41690973 v41690974 --last 12 --output multi.csv

# Decode numeric codes
statcan codeset --type uom
statcan codeset --type frequency --format json

出力形式： csv（download/vector のデフォルト）、table（search/metadata/codeset のデフォルト）、json、ndjson

エージェントとスクリプト向け： サブコマンドの前に --json を指定する（または STATCAN_OUTPUT=json を設定する）と、標準出力に単一の JSON エンベロープが、標準エラー出力に hint を含む JSON エラーが出力され、安定した終了コードが返されます（0 成功、2 使用方法の誤り、3 見つからない、4 拒否、5 再試行可能、6 空）。--output を指定すると、ファイルの概要（行数、列数、期間範囲、系列数）がエンベロープに含まれるため、ファイルを読み戻す必要はありません。詳細：機械可読モード。

パイプ処理の例：

# Top 10 by value (run `statcan metadata <pid>` first to find real dimension IDs)
statcan download 14-10-0287-01 --key "1.1.1" --last 1 --format csv \
  | awk -F',' 'NR>1' | sort -t',' -k5 -rn | head -10

# Extract unique geographies (run `statcan metadata <pid>` first to find real dimension IDs)
statcan download 14-10-0287-01 --key "1.1.1" --last 1 --format csv \
  | awk -F',' 'NR>1 {print $1}' | sort -u

# Chain search → download (run `statcan metadata <pid>` first to find real dimension IDs)
PID=$(statcan search "CPI" --format json | python3 -c "import sys,json; print(json.load(sys.stdin)[0]['Product ID'])")
statcan download $PID --key "1.1.1" --last 12 --output cpi.csv

CLI の完全なリファレンスについては、src/cli/README.md を参照してください。

---

機能とツール

SDMX ツール — サーバー側でフィルタリングしたデータ取得

リクエストした範囲のデータだけが返されます。テーブル全体をダウンロードする必要はありません。

ツール	説明
get_sdmx_structure	テーブルのディメンションコードリストとキー構文を取得します。get_sdmx_data の前に呼び出してください。
get_sdmx_data	productId とキーでフィルタリングした観測値をインラインで返し、系列ごとにまとめます。各系列のラベル、VECTOR_ID、UOM は一度だけ出力され、その後に数値の [period, value] ペアが続きます（観測値は最大 500 件）。
query_sdmx	観測値を取得し、一時的なインメモリテーブル上で読み取り専用の SQL クエリを 1 つサーバー側で実行します。結果のみを返します。ホスト型サーバーで動作し、取得行数に上限はありません。
get_sdmx_vector_data	SDMX を介して単一の vectorId の観測値を取得します（系列ごとにまとめた同じ形式で出力）。
get_sdmx_key_for_dimension	ディメンションのすべての末端メンバー ID を、すぐに貼り付けて使える OR キーとして返します。合計と小計は除外されるため、合算や順位付けで二重カウントされません（例：NOC、CMA）。

キー構文（get_sdmx_data に渡します）：

• "1.2.1" — 地域=1、性別=2、年齢=1
• ".2.1" — すべての地域（ワイルドカード）、性別=2、年齢=1
• "1+2.2.1" — 地域 1 または 2、性別=2、年齢=1

注： ワイルドカード（.）を使うと、合計や親集計を含む、ディメンションのすべてのメンバーが返されます。合算や順位付けには、get_sdmx_key_for_dimension の末端コードを使用してください。大きなワイルドカード指定では get_sdmx_data の 500 行上限を超えることがあります。その場合は query_sdmx を使用してください。

WDS の検索とメタデータ

ツール	説明
search_cubes_by_title	StatCan のすべてのテーブルを対象に全文検索します。AND 条件で検索し、結果は最大 25 件です。アーカイブ済みのテーブルよりも現行テーブルが先に表示されます。
get_all_cubes_list / _lite	テーブル一覧をページ分割して取得します（offset/limit、既定では 1 ページあたり 100 件）。
get_cube_metadata	ディメンション情報、メンバー一覧、日付範囲を取得します。summary=True を指定すると、ディメンションごとのメンバー数を最大 10 件に制限します。
get_code_sets	StatCan の数値コードをデコードします。既定では要約を返します。大きなセットでは code_set="uom", search="percent" を指定してください。

WDS の系列解決と変更検出

ツール	説明
get_series_info	{productId, coordinate} の組を vectorId とメタデータに解決します。
get_series_info_from_vector	vectorId を productId、coordinate、タイトル、頻度に解決します。
get_changed_cube_list	指定した日に更新されたテーブルを取得します。
get_changed_series_list	本日更新された系列を取得します（ET 08:30 以降に利用可能）。過去の日付については、get_changed_cube_list(date) を使用してください。
get_changed_series_data_from_cube_pid_coord	座標について本日変更されたデータポイントを取得します（ET 08:30 より前、または変更がない場合は changed: false）。
get_changed_series_data_from_vector	vectorId について本日変更されたデータポイントを取得します（ET 08:30 より前、または変更がない場合は changed: false）。
get_bulk_vector_data_by_range	公開日の範囲でフィルタリングした複数のベクトルを取得します。

複合ツールとデータベースツール (ローカル／stdio モードのみ)

これらのツールは、ホスト型の Render サーバーでは利用できません。SQLite はプロセスごとに独立しており、ユーザー間で共有されないためです。

ツール	説明
fetch_sdmx_to_database	SDMX の観測値（productId + key）を観測データストアに取得します。行数の上限はなく、行がコンテキストに入りません。table_name はビューになります。
fetch_vectors_to_database	参照期間の範囲を指定して、同じデータストアにベクトルを取得します。table_name はビューになります。
store_cube_metadata	キューブのメタデータ全体を SQLite に取得します。SQL を使ってすべてのメンバーと vectorId を参照できます。
query_database	ローカルの SQLite データベースに対する読み取り専用の SQL クエリです。
create_table_from_data / insert_data	独自データのテーブルを作成、または既存のテーブルに追加します。
list_tables / get_table_schema / drop_table	データベースのユーティリティです（テーブルとビューに対応。list_tables はデータストアのサイズも報告します）。

観測データストア。 どちらの取得ツールも、共有される2つのテーブルに対してアップサートを行うため、呼び出しごとに新しいテーブルへコピーするのではなく、データが蓄積されます。

テーブル	1行あたり	主な列
_statcan_series	系列	series_id（<productId>:<SDMX key>、例：18100004:2.2）、product_id、vector_id、dims_json（ラベル）、uom
_statcan_observations	系列 × 期間	series_id、ref_date（期間の開始日）、period（2026、2026-Q2、2026-08）、value、status、source、fetched_at、release_time

• 再取得時には値がその場で更新されます。各取得処理では、観測値が何件 new、revised、unchanged だったかが報告されます。
• 同じ系列の SDMX と WDS の取得結果は同じ行を共有します（WDS の座標は同じ SDMX キーに対応します）。
• table_name は、その呼び出しで取得した系列と期間を対象とするビューで、以前と同じ列（次元ラベル、period、value、VECTOR_ID、UOM、...）を持ちます。
• テーブルをまたいだ分析にスキーマの調査は不要です。

-- Seasonal component: CPI not seasonally adjusted (18100004) minus seasonally adjusted (18100006)
SELECT nsa.period, ROUND(nsa.value - sa.value, 2) AS seasonal
FROM _statcan_observations nsa JOIN _statcan_observations sa USING (ref_date)
WHERE nsa.series_id = '18100004:2.2' AND sa.series_id = '18100006:1.1'
ORDER BY ref_date DESC;

一般的なワークフロー

Claude.ai ウェブ版（ホスト型サーバー）：

1. search_cubes_by_title("unemployment rate")
   → productId e.g. 14100287

2. get_sdmx_structure(productId=14100287)
   → dimension positions + sample codes

3. get_sdmx_key_for_dimension(productId=14100287, dimension_position=3)
   → or_key for large dimensions

4. get_sdmx_data(productId=14100287, key=".2.1", lastNObservations=24)
   → returns download_csv URL

5. Python script: validate URL domain → write to ./statcan_14100287.csv → analyze → print summary

Claude Code（bash サンドボックス）：

statcan search "unemployment rate"
statcan metadata 14100287
statcan download 14-10-0287-01 --key "1.1.1" --last 24 --output ./lfs.csv  # run `statcan metadata <pid>` first to find real dimension IDs
awk -F',' 'NR>1 && $1=="Canada"' ./lfs.csv | sort -t',' -rn -k5 | head -10

---

プロジェクト構成

src/
├── api/
│   ├── cube/
│   │   ├── discovery.py         # search_cubes_by_title, get_all_cubes_list
│   │   ├── metadata.py          # get_cube_metadata
│   │   └── series.py            # get_series_info, change detection
│   ├── vector/
│   │   └── vector_tools.py      # vector series, bulk range fetch
│   ├── sdmx/
│   │   └── sdmx_tools.py        # get_sdmx_structure, get_sdmx_data, query_sdmx, get_sdmx_key_for_dimension
│   ├── composite_tools.py       # fetch_sdmx_to_database, fetch_vectors_to_database, store_cube_metadata (stdio only)
│   └── metadata_tools.py        # get_code_sets
├── cli/
│   ├── main.py                  # statcan CLI entry point (Typer app)
│   ├── output.py                # write_output, format helpers
│   └── commands/
│       ├── search.py            # statcan search
│       ├── metadata.py          # statcan metadata
│       ├── download.py          # statcan download
│       ├── vector.py            # statcan vector
│       └── codeset.py           # statcan codeset
├── db/                          # SQLite: observation store (store.py), per-request SQL for query_sdmx (ephemeral.py), schema, queries
├── models/                      # Pydantic input models
├── util/
│   ├── registry.py              # ToolRegistry — @decorator → MCP Tool schema
│   ├── truncation.py            # Response truncation + pagination guidance
│   ├── sdmx_xml.py              # SDMX-ML (structure-specific XML) → labelled tabular rows
│   └── cache.py                 # 1-hour TTL cache for cube list
├── config.py                    # BASE_URL, SDMX_BASE_URL, RENDER_BASE_URL, TRANSPORT, PORT
└── server.py                    # create_server(), MCP Prompts, resources, HTTP transport, CLI

---

既知の問題

問題	状態	回避策
Claude Desktop で「Unable to open database file」と表示される	対応中	設定に --db-path /Users/<you>/.statcan-mcp/statcan_data.db を指定します
信頼ストアに問題がある場合の SSL 検証	設定可能	検証はデフォルトで有効です。システムが StatCan の証明書を検証できない場合に限り、STATCAN_VERIFY_SSL=false を設定します
lastNObservations と startPeriod/endPeriod の併用で 406 が発生する	対応中	どちらか一方を使用してください
ワイルドカード／OR 行が欠落または誤ったラベルになる、VECTOR_ID/UOM が誤っている	v0.12.0 で修正済み	StatCan の SDMX-JSON インデックスのエンコーディングが原因でした。データは現在、構造固有の XML として読み込まれます（#90）
コンテキストのオーバーフローによってデータが捏造される可能性がある	軽減済み	生の行データがコンテキストに入らないよう、query_sdmx（ホスト型）または fetch_sdmx_to_database（ローカル）を使用してください。get_sdmx_data はインラインの行数を500件に制限します

---

貢献者

コード、修正、バグ報告で貢献してくださった皆さまに感謝します。

• @Aryan-Jhaveri：作成者およびメンテナー
• @dannyward630：get_changed_series_list が StatCan の日付なしエンドポイントを使うように修正（#130）

協力したい方は、CONTRIBUTING.md をご覧ください。

---