Statistics Canada MCP Server

Fetch filtered time-series observations from a StatCan table via SDMX REST. Filtering is done server-side — only the requested slice is returned. Call get_sdmx_structure first to see dimension positions and valid codes. Key syntax (dot-separated codes in dimension position order): "1.2.1" = Geography=1 (Canada), Gender=2 (Men+), Age=1 (All ages) ".2.1" = all geographies, Gender=2, Age=1 (wildcard — preferred for multi-geo) "1+2.2.1" = Geography 1 or 2, Gender=2, Age=1 (OR) IMPORTANT — key position codes: - Use member IDs from get_cube_metadata(), NOT SDMX codelist positions from get_sdmx_structure(). Member IDs and SDMX codelist codes are the same numbers. - Wildcard (omit a position) returns EVERY member of that dimension, including totals and parent aggregates — on large dimensions (e.g. 309 NOC occupations) that can exceed the 500-row cap here; use query_sdmx or fetch_sdmx_to_database instead. - To sum or rank across a hierarchy without double-counting totals, use leaf codes: get_sdmx_key_for_dimension(productId, dimension_position) returns them as an OR key. Time filtering (use one or the other, not both): lastNObservations=12 → last 12 periods (e.g. 1 year of monthly data) startPeriod="2020" → from 2020 onwards (annual); "2020-01" for monthly endPeriod="2023-12" → up to Dec 2023 LIMITATION: StatCan rejects combining lastNObservations with startPeriod/endPeriod (returns 406). Output is grouped by series: each entry in "series" holds the fields that are constant for that series once (dimension labels, _series_key, VECTOR_ID, UOM, SCALAR_FACTOR, ...) plus "observations" as [period, value] pairs with numeric values (null = suppressed). A third element {field: label} appears only on observations with their own attributes (e.g. a STATUS flag). Over 100 observations, the result is a summary instead (summary=true): fields shared by all series once in "common", varying dimensions in "varies", and per series count, period_range, latest, min and max. Pass full=true for every observation (capped at 500), or use query_sdmx to compute over all of them. Growth, percent change, averages, ranking or comparisons? Use query_sdmx instead of computing by hand from these values. Fetch each series and period range once: do not re-fetch periods you already have from get_sdmx_vector_data. IMPORTANT: In your final response to the user, you MUST cite the source of your data. This means including the _sdmx_url, table information and productId/key in your response.

Return all leaf member IDs for a single dimension as a ready-to-use OR key string. Use this before get_sdmx_data when a dimension has many codes (e.g. 162 NOC minor groups, hundreds of CMA geographies). Avoids the need to call get_cube_metadata and manually parse a large JSON response. Leaf codes are codes with no children — the lowest-level members in a hierarchy. For flat (non-hierarchical) codelists every code is a leaf. Example: get_sdmx_key_for_dimension(productId=98100452, dimension_position=6) → { "dimension_id": "Occupation_...", "dimension_name": "Occupation - Minor group - NOC 2021", "position": 6, "leaf_count": 162, "total_count": 309, "or_key": "7+11+12+13+16+18+21+23+...", "note": "Paste or_key at position 6 in your get_sdmx_data key." } Then use the or_key directly: get_sdmx_data(productId=98100452, key="7.3.1.1.1.<or_key>.1", ...)

Fetch the Data Structure Definition (DSD) for a StatCan table via SDMX REST. Returns dimension codelists with code IDs, names, and parent hierarchy. Use this BEFORE get_sdmx_data to understand the key syntax for that table. Each dimension entry includes: - id: dimension identifier (e.g. "Geography") - position: its slot in the dot-separated key string (1-based) - codelist: the SDMX codelist ID (e.g. "CL_Geography") - codes: list of {id, name, ?parent} — truncated to 10 for large codelists - _code_count / _truncated: total size and truncation flag Key construction rules: - "1.2.1" = position-1 code 1, position-2 code 2, position-3 code 1 - ".2.1" = wildcard position 1 (all geographies), Gender=2, Age=1 - "1+2.2.1" = Geography 1 or 2 (OR syntax) - WDS memberIds == SDMX codelist codes — no translation needed IMPORTANT: In your final response to the user, you MUST cite the source of your data. This means including the _sdmx_url.

Fetch time-series observations for a single StatCan vector via SDMX REST. Simpler alternative to get_sdmx_data when you already know the vectorId. Use get_series_info (productId + coordinate) to find vectorIds. Time filtering (use one or the other, not both): lastNObservations=5 → last 5 periods startPeriod="2020-01" → from Jan 2020 (monthly); "2020" for annual endPeriod="2023-12" → up to Dec 2023 LIMITATION: StatCan rejects combining lastNObservations with startPeriod/endPeriod (returns 406). Output has the same shape as get_sdmx_data: one entry in "series" with its constant fields once, then "observations" as [period, value] pairs. Over 100 observations it is a summary (latest, min, max) unless full=true. Growth, percent change or averages? Use query_sdmx instead of computing by hand. IMPORTANT: In your final response to the user, you MUST cite the source of your data. This means including the _sdmx_url and vectorId in your response.

Fetch SDMX observations and run ONE read-only SQL query over them server-side, returning only the query result. Nothing is stored — the data is loaded into a temporary in-memory table named `data` and discarded after the query. *** Use this for compute/compare/rank questions ("which province grew fastest", "average since 2020", "year-over-year change") instead of pulling raw rows with get_sdmx_data and doing arithmetic yourself. It is not limited to 500 rows. *** Same productId, key and time parameters as get_sdmx_data (see that tool for key syntax and wildcard rules). lastNObservations cannot be combined with startPeriod/endPeriod. Table `data` columns: one per dimension (names sanitized: spaces/punctuation → '_'), "period" (TEXT, e.g. "2024" or "2024-03"), "value" (REAL, NULL = suppressed), plus SDMX attributes like VECTOR_ID, UOM, SCALAR_FACTOR, STATUS. Quote mixed-case column names with double quotes. Example — CPI growth by province since Jan 2020: productId=18100004, key="2+3+5+6.2", startPeriod="2020-01", sql: SELECT "Geography", MAX(CASE WHEN period = '2025-12' THEN value END) / MAX(CASE WHEN period = '2020-01' THEN value END) - 1 AS growth FROM data GROUP BY 1 ORDER BY growth DESC If the SQL fails, the response includes `table_columns` — fix the query and retry. Limits: one statement, SELECT only, ~2s execution time, result capped at 500 rows. IMPORTANT: In your final response, cite the _sdmx_url, productId and key used.

Get the list of data tables/cubes that were updated on a specific date (YYYY-MM-DD). Disables SSL Verification. Corresponds to: GET /getChangedCubeList/{date} Returns: List[Dict[str, Any]]: A list of dictionaries describing changed cube objects. IMPORTANT: In your final response to the user, you MUST cite the source of your data. For changed cubes, this means including the ProductId (pid) and Title.

Get the data points of a series (by ProductId + Coordinate) that changed TODAY only. StatCan publishes at 08:30 ET; before then, or on a day the series did not change, this returns changed=false. For past releases use get_changed_cube_list(date). Coordinates are automatically padded to 10 dimensions. Disables SSL Verification. Corresponds to: POST /getChangedSeriesDataFromCubePidCoord Returns: Dict[str, Any]: The changed series data object, or {"productId", "coordinate", "changed": false, "message"} when nothing changed today. Raises: httpx.HTTPStatusError: If the API returns an error status code. ValueError: If the API response format is unexpected or status is not SUCCESS. Exception: For other network or unexpected errors. IMPORTANT: In your final response to the user, you MUST cite the source of your data. For changed series data, this means including the VectorId, ProductId (pid), and Coordinate.

Get the data points of a series (by Vector ID) that changed TODAY only. StatCan publishes at 08:30 ET; before then, or on a day the series did not change, this returns changed=false. For past releases use get_changed_cube_list(date). Disables SSL Verification. Corresponds to: POST /getChangedSeriesDataFromVector Returns: Dict[str, Any]: The changed series data object, or {"vectorId", "changed": false, "message"} when nothing changed today. Raises: httpx.HTTPStatusError: If the API returns an error status code. ValueError: If the API response format is unexpected or status is not SUCCESS. Exception: For other network or unexpected errors. IMPORTANT: In your final response to the user, you MUST cite the source of your data. For changed series data, this means including the VectorId.

Get the list of series (vectorId, productId, coordinate, releaseTime) updated today. Statistics Canada publishes this list after 08:30 ET; the endpoint does not accept a date. For a historical release date, use get_changed_cube_list(date) to list the cubes updated on that date. Disables SSL Verification. Corresponds to: GET /getChangedSeriesList Returns: List[Dict[str, Any]]: A list of dictionaries describing changed series objects. Raises: Exception: If the API returns an unexpected status code or network error. ValueError: If today's list has not been released or the response format is unexpected. IMPORTANT: In your final response to the user, you MUST cite the source of your data. For changed series, this means including the VectorId.

Provides a complete inventory of data tables available via the API, including dimension-level details. Disables SSL Verification. Corresponds to: GET /getAllCubesList Results are paginated. Default returns first 100 cubes. Use offset/limit to page through. Prefer search_cubes_by_title if you know what you're looking for. IMPORTANT: In your final response to the user, you MUST cite the source of your data. For cubes, this means including the ProductId (pid) and the Title.

Provides a complete inventory of data tables available via the API, excluding dimension or footnote information (lighter version). Disables SSL Verification. Corresponds to: GET /getAllCubesListLite Results are paginated. Default returns first 100 cubes. Use offset/limit to page through. Prefer search_cubes_by_title if you know what you're looking for. IMPORTANT: In your final response to the user, you MUST cite the source of your data. For cubes, this means including the ProductId (pid) and the Title.

Resolve one or more {productId, coordinate} pairs to series metadata (vectorId, titles, frequency, UOM, etc.) in a single API call. Use this to find vectorIds before fetching data with get_sdmx_data or get_sdmx_vector_data. Pass one item or many — same tool either way. Each result already includes vectorId, frequencyCode, scalarFactorCode and memberUomCode, so do not call get_series_info_from_vector for the same series. Coordinates are automatically padded to 10 dimensions. Corresponds to: POST /getSeriesInfoFromCubePidCoord (accepts array) NOTE: Response fields like scalarFactorCode, frequencyCode, and memberUomCode use StatCan numeric codes. Call get_code_sets() to decode them (e.g. frequencyCode 6 = "Monthly", scalarFactorCode 0 = "Units"). Returns: List of series metadata dicts, paginated with _guidance if >50 results. Raises: httpx.HTTPStatusError: If the API returns an error status code. ValueError: If no items return SUCCESS. Exception: For other network or unexpected errors. IMPORTANT: In your final response cite the ProductId and Coordinate for each series.

Request series metadata (productId, coordinate, titles, frequency, etc.) by Vector ID. Use only when you start from a vectorId: get_series_info already returns this metadata for series it resolved. Disables SSL Verification. Corresponds to: POST /getSeriesInfoFromVector Returns: Dict[str, Any]: A dictionary containing the series metadata object. Raises: httpx.HTTPStatusError: If the API returns an error status code. ValueError: If the API response format is unexpected or status is not SUCCESS. Exception: For other network or unexpected errors. IMPORTANT: In your final response to the user, you MUST cite the source of your data. For series info, this means including the VectorId, ProductId (pid), and Coordinate.

Fetches bulk data for multiple vectors filtered by *release date* range (YYYY-MM-DDTHH:MM), NOT by reference period. Use this when you want data released within a specific date/time window (e.g., "all updates released yesterday"). *** IMPORTANT: release date vs reference period *** - Use THIS tool when you want: "data released between date A and date B" - Use get_sdmx_vector_data (startPeriod/endPeriod) when you want: "data for the time period YYYY to YYYY" get_sdmx_vector_data is more reliable and filters by reference period, not release date. *** LARGE RESPONSE WARNING *** This tool can return hundreds of flattened data points. If the response exceeds context limits, narrow the request: use fewer vectorIds, or use offset/limit pagination to page through results in smaller chunks. Response is pre-flattened: each element is one data point with vectorId, productId, coordinate, and all value fields injected at the top level. Disables SSL Verification. Corresponds to: POST /getBulkVectorDataByRange Returns: List[Dict[str, Any]]: Flat list of data point dicts, each tagged with vectorId, productId, and coordinate. Raises: httpx.HTTPStatusError: If the API returns an error status code. ValueError: If the API response format is unexpected or no vectors return SUCCESS. Exception: For other network or unexpected errors. IMPORTANT: In your final response to the user, you MUST cite the source of your data. For vector data, this means including the VectorId and Release Time.

Decode StatCan WDS numeric codes (e.g. frequencyCode 6 = Monthly, scalarFactorCode 0 = units). Corresponds to: GET /getCodeSets Without arguments, returns a summary: small code sets (scalar, frequency, symbol, status, ...) in full, and only entry counts for large ones (uom, survey, subject, classificationType). Request a large set with code_set, and narrow it with search: get_code_sets(code_set="uom", search="percent") Returns: Dict[str, Any]: {code_set_name: [entries]} for the returned sets, plus "_large_code_sets" {name: entry count} in the summary. Raises: ValueError: If code_set is unknown or the API response is not SUCCESS. IMPORTANT: In your final response to the user, you MUST cite the source of your data. For code sets, this means specifying which code set table or definition is being used.

Retrieves detailed metadata for a specific data table/cube using its ProductId. Includes dimension info, titles, date ranges, codes, etc. Disables SSL Verification. Corresponds to: POST /getCubeMetadata Start with summary=True (default). The summary strips noise (French translations, archive codes, footnotes) and shows only 3 sample members per dimension with _next_steps guidance. Safe for all context window sizes. Set summary=False only if you need the full raw member list or all API fields. To browse dimension codes for get_sdmx_data key construction, use get_sdmx_structure. To resolve a coordinate to a vectorId, use get_series_info. Returns: Dict[str, Any]: The metadata object for the specified cube on success. Raises: httpx.HTTPStatusError: If the API returns an error status code. ValueError: If the API response format is unexpected or status is not SUCCESS. Exception: For other network or unexpected errors. IMPORTANT: In your final response to the user, you MUST cite the source of your data. For cubes, this means including the ProductId (pid) and the Title.

Searches for data cubes/tables where the English or French title contains the provided search term (case-insensitive). Multiple keywords use AND logic (e.g., "tobacco smoking age" finds cubes containing ALL three words). Returns max_results matches (default 10) from offset. Returns {"data": [...], "total_matches": N, "showing": M, ?"next_offset"}. Each result has productId, cubeTitleEn, cubeStartDate, cubeEndDate, frequencyCode, releaseTime and archived (true = discontinued table); current tables come first. The top 3 also have key_template: the table's SDMX dimensions in key order (e.g. "Geography.Products_and_product_groups"), one key position each. IMPORTANT: In your final response to the user, you MUST cite the source of your data. For cubes, this means including the ProductId (pid) and the Title.