📊 Statistics Canada API MCP Server

加拿大统计局 MCP 服务

用于加拿大统计局 Web Data Service (WDS) 和 SDMX REST API 的 MCP 服务和命令行工具。为任何 MCP 客户端（Claude、Cursor、VS Code Copilot、Gemini）提供对加拿大统计数据的结构化访问。还包含独立的 statcan 命令行工具，可直接下载数据，无需大模型。

托管在 Render 上——大多数用户无需安装。请参阅快速开始。

⚠️ 大模型可能会编造数据。请务必对照加拿大统计局官方来源核实重要数据。

---

目录

• 快速开始
• 示例
• 按客户端配置
• Claude.ai 如何使用此服务
• MCP 提示词
• statcan 命令行工具
• 功能和工具
• 项目结构
• 已知问题
• 贡献者

---

快速开始

选择适合你的选项。使用选项 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，无数据库）

运行本地服务，使用与托管版本相同的工具。

步骤 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 命令行工具（无需大模型）

直接从终端下载加拿大统计局数据。请参阅 statcan 命令行工具。

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

---

示例

聊天示例

数据集	查询	演示	来源
加拿大温室气体排放	“为加拿大整体过去 4 年的温室气体排放创建一个简单的可视化图表”	聊天	表 38-10-0097-01
加拿大国际服务贸易	“对过去 6 个月的国际服务贸易进行快速分析，并创建可视化图表”	聊天	表 12-10-0144-01
安大略省建筑施工价格指数	“为 2023 年第 4 季度至 2024 年第 4 季度的安大略省建筑价格指数生成可视化图表”	聊天	表 18-10-0289-01
加拿大失业率仪表板	“使用 statcan mcp 创建加拿大失业率仪表板”	聊天	表 14-10-0287-01

仪表板示例

标题	链接	来源
加拿大关键矿产经济	仪表板	表 36-10-0708-01
万物价格：CPI 仪表板 2015–2026	仪表板	表 18-10-0004-01
加拿大生物医学与生物技术产业	仪表板	表 27-10-0297-01

---

按客户端配置

托管服务（选项 1）

Claude Desktop — 设置 → 连接器 → 添加自定义连接器

• 名称：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，然后配置客户端。

大多数客户端需要使用 mcp-proxy 在标准输入/输出 ↔ HTTP 之间进行桥接。Claude Code 可原生连接。

Claude Desktop — 设置 → 开发者 → 编辑配置：

{
  "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。

---

完全本地 / 标准输入/输出（选项 3）

Claude Desktop — 设置 → 开发者 → 编辑配置：

{
  "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 — 使用 uvx statcan-mcp-server 作为标准输入/输出命令。

---

Claude.ai 如何使用此服务

Claude.ai（Web）没有 Bash 沙箱，无法运行 Shell 命令。它会改用 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 提示词

此服务提供五个提示词，在支持的客户端中可通过斜杠命令访问。每个提示词都包含双重说明——适用于 Claude Code（Bash）和 Claude.ai Web（Python 脚本）。

提示词	说明内容
/statcan-data-lookup	端到端流程：搜索 → 查看结构 → 构建 key → 下载到本地文件 → 分析
/sdmx-key-builder	SDMX key 语法：通配符、OR keys、时间参数、下载 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

独立 CLI，无需大模型即可下载 StatCan 数据。输出适合通过管道处理的 CSV/JSON 到 stdout；进度和错误输出到 stderr。

探索表格（搜索，然后查看元数据，最后下载）：

Agent 模式（--json 信封、类型化退出码、statcan describe）：

录屏由 assets/tapes/ 中的脚本通过 VHS 生成：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

**用于 Agent 和脚本：**在子命令前添加 --json（或设置 STATCAN_OUTPUT=json），即可在 stdout 上获取一个 JSON 信封，在 stderr 上获取带有 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 查询 — 仅返回查询结果。适用于托管服务；获取数据时不限制行数。
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，默认每页 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、坐标、标题、频率。
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 还会报告存储大小）。

观测值存储。 两种获取工具都会写入两个共享表，因此数据会不断累积，而不是每次调用都复制到新表中：

表	每行对应	关键列
_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 key）。
• 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。

---