Access Statistics Canada data via the Web Data Services API
Statistics Canada MCP Server (io.github.Aryan-Jhaveri/mcp-statcan)
This MCP server accesses Statistics Canada data via the Web Data Services API. It is identified by the slug io-github-aryan-jhaveri-mcp-statcan and is associated with topics including data-analysis, mcp, mcp-server, canada, llm, open-data, python, sdmx, statistics, and wds.
๐ ๏ธ Key Features
Web Data Services API integration for Statistics Canada data access
๐ Use Cases
Accessing Statistics Canada open data for data-analysis and statistics workflows
Using MCP with LLM applications that need Canadian datasets
โก Developer Benefits
Python support (Python 3.10+) indicated in the README excerpt
Uses Model Context Protocol (MCP) per referenced MCP branding
โ ๏ธ Limitations
Tool count and specific MCP tools/endpoints are not included in the provided source excerpt
SDMX-related details are not specified beyond the sdmx topic
Find StatCan tables by title keywords. Returns productId, title, dates and
frequency; each includes key_template, the dimension order of the SDMX key.
Parameters3
search_term
string
required
Keywords, all must appear in the title (English or French).
max_results
integer
optional
offset
integer
optional
next_offset from the previous page.
Raw schema
{
"type": "object",
"properties": {
"search_term": {
"description": "Keywords, all must appear in the title (English or French).",
"type": "string"
},
"max_results": {
"default": 10,
"type": "integer"
},
"offset": {
"default": 0,
"description": "next_offset from the previous page.",
"type": "integer"
}
},
"required": [
"search_term"
]
}
get_sdmx_structure
A table's dimensions in key order with their codes (id, name, parent).
Use search to find the codes for labels like 'Ontario' instead of guessing.
Parameters3
productId
integer
required
8-digit table id (table 18-10-0004-01 โ 18100004).
search
string
optional
Return only codes whose name contains this text (case-insensitive), across all dimensions, e.g. 'Ontario'. Separate several terms with ';'.
dimension
integer
optional
Key position: return every code of that dimension (default: first 10 per dimension), plus leaf_key, its lowest-level codes as a '+' OR.
Raw schema
{
"type": "object",
"properties": {
"productId": {
"description": "8-digit table id (table 18-10-0004-01 โ 18100004).",
"type": "integer"
},
"search": {
"type": "string",
"description": "Return only codes whose name contains this text (case-insensitive), across all dimensions, e.g. 'Ontario'. Separate several terms with ';'."
},
"dimension": {
"type": "integer",
"description": "Key position: return every code of that dimension (default: first 10 per dimension), plus leaf_key, its lowest-level codes as a '+' OR."
}
},
"required": [
"productId"
]
}
get_sdmx_data
Observations for productId + key, or one vectorId. Over 100 observations you get a
per-series summary. Pass sql to compute over every row (growth, averages, ranking)
server-side. Cite _sdmx_url.
Parameters9
productId
integer
optional
key
string
optional
With productId: one code per dimension in position order, joined by '.'; '+' for OR ('1+2.2'); empty for all members ('.2', includes totals).
vectorId
integer
optional
Instead of productId + key: one series.
lastNObservations
integer
optional
Last N periods per series.
startPeriod
string
optional
'2020', '2020-01' or '2020-Q1'. Not with lastNObservations.
endPeriod
string
optional
sql
string
optional
One SELECT over all fetched rows as table 'data', returning only its result. Use it for growth, averages, rankings. Columns: one per dimension (non-alphanumerics โ '_', double-quote them), period (TEXT), value (REAL), VECTOR_ID, UOM, STATUS.
full
boolean
optional
Every observation (max 500) instead of a summary when over 100.
format
string
optional
csv: to save rows to a file, copy it verbatim. All observations (max 500), a row per series, a column per period; shared fields as '# name: value' lines.
Raw schema
{
"type": "object",
"properties": {
"productId": {
"type": "integer"
},
"key": {
"type": "string",
"description": "With productId: one code per dimension in position order, joined by '.'; '+' for OR ('1+2.2'); empty for all members ('.2', includes totals)."
},
"vectorId": {
"type": "integer",
"description": "Instead of productId + key: one series."
},
"lastNObservations": {
"type": "integer",
"description": "Last N periods per series."
},
"startPeriod": {
"type": "string",
"description": "'2020', '2020-01' or '2020-Q1'. Not with lastNObservations."
},
"endPeriod": {
"type": "string"
},
"sql": {
"type": "string",
"description": "One SELECT over all fetched rows as table 'data', returning only its result. Use it for growth, averages, rankings. Columns: one per dimension (non-alphanumerics โ '_', double-quote them), period (TEXT), value (REAL), VECTOR_ID, UOM, STATUS."
},
"full": {
"default": false,
"description": "Every observation (max 500) instead of a summary when over 100.",
"type": "boolean"
},
"format": {
"default": "json",
"description": "csv: to save rows to a file, copy it verbatim. All observations (max 500), a row per series, a column per period; shared fields as '# name: value' lines.",
"enum": [
"json",
"csv"
],
"type": "string"
}
},
"required": []
}
get_series_info
Series metadata for productId + coordinates, or vectorIds: vectorId, key, title,
frequency, unit of measure and scalar (decoded), decimals.
Parameters3
productId
integer
optional
coordinates
array
optional
With productId: dot-separated member ids, e.g. ['14.2'].
MCP server and CLI for Statistics Canada's Web Data Service (WDS) and SDMX REST API. Gives any MCP client โ Claude, Cursor, VS Code Copilot, Gemini โ structured access to Canadian statistical data. Includes a standalone statcan CLI for direct downloads without an LLM.
Hosted on Render โ no install required for most users. See Quick Start.
Pick the option that fits you. You don't need to install anything for Option 1.
Option 1 โ Use the hosted server (recommended)
Connect directly to the public server on Render. No uv, no terminal, no local setup.
Claude Desktop / Claude.ai
Open Settings โ Connectors โ Add Custom Connector
Name: mcp-statcan
URL: https://mcp-statcan.com/mcp
Save and restart
Claude Code
bash
claude mcp add statcan --transport http https://mcp-statcan.com/mcp --scope global
The hosted server provides all WDS + SDMX tools. Database tools (SQLite) require local setup (Option 3) โ they are intentionally excluded from the shared server.
Option 2 โ Self-host HTTP (WDS + SDMX, no DB)
Run a local server with the same tools as the hosted version.
Pass --db-path with an absolute path. Claude Desktop overrides the subprocess HOME env var, which can break default path resolution.
Claude Code
bash
claude mcp add statcan --scope global -- uvx statcan-mcp-server
Cursor / VS Code / Gemini โ use uvx statcan-mcp-server as the stdio command.
How Claude.ai Uses This Server
Claude.ai (web) has no bash, and its code sandbox can't reach StatCan, so all data comes through the connector's MCP tools.
The pattern:
code
1. Discovery (small payloads):
search_cubes_by_title("labour force") โ productId + key_template
get_sdmx_structure(productId=..., search="Ontario;Employment") โ codes by label
2. Answers: get_sdmx_data(..., sql="SELECT ...") โ only the result comes back
3. Files: get_sdmx_data(..., format="csv") โ copy the CSV verbatim into a file
Use sql for rankings, growth and averages; use format="csv" only when the rows need to go into a file.
After a server update, disconnect and reconnect the connector in claude.ai to refresh the tool list.
Claude Code (bash sandbox) uses the statcan CLI instead:
bash
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 Prompts
The server ships five prompts accessible as slash commands in supported clients. Each has two sets of instructions: Claude Code (the statcan CLI in bash) and Claude.ai web (the MCP tools, with sql and format="csv" to keep rows out of context).
Prompt
What it teaches
/statcan-data-lookup
End-to-end: search โ structure โ build key โ fetch (CLI to a file, or MCP tools with sql) โ analyze
/sdmx-key-builder
SDMX key syntax: wildcards, OR keys, time parameters, download URL format
/statcan-download
Download a specific table: CLI commands, or the MCP tools on Claude.ai
/statcan-explore
Sample before committing: 3-period fetch, column layout, size estimate
/statcan-vector-pipeline
Multi-series download and cross-series comparison
The tool calls in the prompts follow the active toolset.
Terminal recording: statcan --json download writes a CSV and prints a summary envelope; a missing product returns a JSON error with exit code 3; statcan describe lists exit codes
Recordings are generated from the scripts in assets/tapes/ with VHS: vhs assets/tapes/cli-agent.tape.
Install:
bash
pip install statcan-mcp-server # or: uvx statcan-mcp-server (no install)
Commands:
code
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
Common usage:
bash
# 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
Output formats:csv (default for download/vector), table (default for search/metadata/codeset), json, ndjson
For agents and scripts: put --json before the subcommand (or set STATCAN_OUTPUT=json) to get one JSON envelope on stdout, JSON errors with a hint on stderr, and stable exit codes (0 ok, 2 usage, 3 not found, 4 rejected, 5 retryable, 6 empty). With --output, the envelope summarizes the file (rows, columns, period range, series count) so it never has to be read back. Details: machine-readable mode.
Pipe patterns:
bash
# 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
Find tables by title keywords (English or French; all must appear). Paged (offset, max_results, default 10); every result includes key_template, the dimension order of the SDMX key.
get_sdmx_structure
A table's dimensions in key order with their codes (id, name, parent). search="Ontario;Employment" finds codes by label across all dimensions; dimension=<position> lists one full dimension plus its leaf_key (lowest-level codes as a + OR).
get_sdmx_data
Observations for productId + key, or one vectorId. Over 100 observations you get a per-series summary unless full=true (max 500 rows). Pass sql to run one read-only SELECT over the table data server-side (growth, averages, rankings) and get back only the result. format="csv" returns compact CSV instead of JSON (see below).
get_series_info
productId + coordinates, or vectorIds: decoded frequency, unit and scalar, English and French title, and the SDMX key.
get_changes
Tables released on a date (default today), or the new data points for one series (vectorId, or productId + coordinate).
CSV output:get_sdmx_data(format="csv") returns one row per series and one column per period, with fields shared by every series written once as # name: value lines. It always returns the rows (ignores full, max 500 observations) and works with sql. It is about 3x smaller than full=true JSON (table 15100032, key 7...: 7,892 to 2,637 characters; 18100004, key .2, last 12: 13,247 to 3,630).
".2.1" โ all geographies (wildcard), Gender=2, Age=1
"1+2.2.1" โ Geography 1 or 2, Gender=2, Age=1
Note: Wildcard (.) returns every member of the dimension, including totals and parent aggregates. For sums or rankings use the leaf_key from get_sdmx_structure(productId, dimension=N), and pass sql to compute over large result sets.
Toolsets
The server publishes one of two toolsets, chosen at startup. core is the default; legacy is the previous 17-tool set (hosted).
Re-fetching updates values in place; each fetch reports how many observations were new, revised or unchanged.
An SDMX and a WDS fetch of the same series share rows (WDS coordinates map to the same SDMX key).
table_name is a view over the series and periods that call fetched, with the same columns as before (dimension labels, period, value, VECTOR_ID, UOM, ...).
Cross-table analysis needs no schema discovery:
sql
-- 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'ORDERBY ref_date DESC;
Typical workflow
Claude.ai web (hosted server):
code
1. search_cubes_by_title("unemployment rate")
โ productId e.g. 14100287
2. get_sdmx_structure(productId=14100287)
โ dimension positions + sample codes
3. get_sdmx_structure(productId=14100287, search="Ontario;Employment")
โ ids of the codes you want, by label
4. get_sdmx_data(productId=14100287, key=".2.1", lastNObservations=24,
sql="SELECT ... FROM data")
โ server-side SQL: only the result comes back (omit sql for the observations)
Claude Code (bash sandbox):
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
Pass --db-path /Users/<you>/.statcan-mcp/statcan_data.db in your config
SSL verification on broken trust stores
Configurable
Verification is on by default; set STATCAN_VERIFY_SSL=false only if your system can't validate StatCan's certificate
lastNObservations + startPeriod/endPeriod โ 406
Active
Use one or the other, not both
Wildcard/OR rows missing or mislabelled; wrong VECTOR_ID/UOM
Fixed in v0.12.0
Caused by StatCan's SDMX-JSON index encoding; data is now read as structure-specific XML (#90)
Context overflow may cause data fabrication
Mitigated
Use get_sdmx_data with sql (hosted) or fetch_sdmx_to_database (local) so raw rows never enter context; get_sdmx_data caps inline rows at 500
Slow or stalled StatCan requests
Mitigated
Stalled requests retry after about 10 s. An incomplete SDMX structure isn't cached, and labels fall back to WDS metadata (the result's _message says so)
Contributors
Thanks to everyone who has contributed code, fixes and bug reports:
@dannyward630: fixed get_changed_series_list to use StatCan's undated endpoint (#130)