MapleStats MCP

One MCP server for Canadian open data.

MapleStats MCP gives AI agents (Claude, Cursor and any MCP client) typed
access to Canadian open data through one server: Statistics Canada
(tables, Census, public use microdata), the Bank of Canada, CMHC, federal
agencies, and federal, provincial, territorial and municipal open-data
portals, in English and French. Every figure comes back with its citation,
its quality flags and its licence, so an answer built on it can be traced to
the publisher and checked.

MapleStats MCP donne aux agents IA un accès structuré aux données
ouvertes canadiennes par un seul serveur, en français et en anglais. Chaque
chiffre revient avec sa citation, ses indicateurs de qualité et sa licence.

Provenance and accountability

• Every figure comes with its citation. A Statistics Canada value carries
  its table and vector, reference period, release date, unit and scale,
  geography and a link to the table's page; a Bank of Canada value, its series
  id and the Valet URL. Every result's provenance block names the source,
  the exact URL and the time of the query. Results are brief by default (the
  values, citation, flags, caveats and limits, long row lists as CSV text);
  detail="full" on call_tool returns the complete provenance block and
  every field.
• Quality flags are kept. StatCan's "use with caution" and "too
  unreliable to be published", preliminary and revised stay on each value;
  public microdata tabulations give a CV and a quality grade per cell where
  the survey's user guide sets one; staff forecasts are marked as forecasts.
• Gaps are named, not filled. When a figure is not published or a period
  is not released yet, the server says so and points to the closest published
  figure. A date range that stops before the newest data gets a note that
  newer data exist.
• Answers can be checked. check_answer re-reads the StatCan and Bank of
  Canada figures an answer cites and reports only the problems.
  reproduce_code writes the R, Python, Stata or Julia script (or Excel Power
  Query) that pulls the same data straight from the publisher, and
  reproduce_workbook gives the rows.
• Licences travel with the data. Each result carries the publisher's
  licence, where it has one, and whether it allows commercial use
  (provenance.commercial_use; the AESO's market data, for one, are
  not_allowed).
• StatCan's data and its documentation. Besides tables and vectors, the
  server reaches definitions, methods and analysis (statcan_reference_*),
  the survey directory and IMDB metadata (statcan_surveys_*), PUMF codebooks
  and user guides (statcan_pumf_*), The Daily's articles and release tables
  (statcan_daily_*) and classifications (rdaas_*).
• Measured. On the 53 questions of the
  Maple Test, MapleStats
  answered 91.8% correctly over three runs (November 3, 2026), with no false
  claims and no invented StatCan table or vector ids. Fifty-three questions are
  few, part of them were chosen from what MapleStats covers, and later
  MapleStats runs are in-sample (details).

Why MapleStats

Built by a statistician, for anyone who works with the numbers: economists,
demographers, policy analysts, researchers, journalists, students, anyone who
needs a Canadian figure they can trust and cite. MapleStats is designed around
the mistakes people actually make with official data, and we test it against
other tools on public benchmarks: see how it does.

• It knows the traps. Constant vs current dollars, family vs individual
  income, annual average vs December over December, survey rent vs listing
  rent: it warns in plain language, and each fitness-for-use caution rests on
  the publisher's own documentation.
• It says when data do not exist. A series that is not published, a period
  not released yet or a date with no data gets a plain no, and the nearest
  figure that does exist.
• The answer can be checked. Before replying, the assistant can send the
  StatCan and Bank of Canada figures it cites to check_answer, which re-reads
  them from the source.
• Your work stays reproducible. It writes the R, Python, Stata or Julia
  script, or the Excel query, that pulls the same data from the source.
• Quality flags and revisions, shown: "use with caution", "too unreliable
  to be published", preliminary and revised are spelled out on every StatCan
  value.
• It only reads, in English and French. The server only reads from public
  sources. The scripts it writes run only if you run them (the full-table ones
  then save the download under data/raw/), and saving a workbook to disk is
  opt-in (MAPLE_EXPORT_DIR, on a local server).

Project vision: docs/PROJECT_GUIDE.md.
Source coverage: docs/ROADMAP.md.
Website: https://maplestats.danielstats.io/.

The easiest way: ask your agent

1. Copy this prompt.
2. Paste it into Claude Code, Codex, Cursor or any agent that can run
   commands on your computer.
3. Restart the agent when it says so, then ask for data.

Connect the MapleStats MCP server to this agent. Follow the setup steps in https://github.com/dsanchezp18/maplestats-mcp

Instructions for the agent doing the setup

The default is the hosted server: nothing to install, no account, no key.

1. Register this remote (HTTP) MCP server under the name maplestats:

   • Claude Code: claude mcp add --transport http --scope user maplestats https://mcp.maplestats.danielstats.io/mcp
   • Codex CLI: codex mcp add maplestats --url https://mcp.maplestats.danielstats.io/mcp
   • Cursor, Claude Desktop and other mcpServers clients: add the entry
     below to the client's config file (Cursor: ~/.cursor/mcp.json; Claude
     Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
     on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows),
     keeping any servers already there.
   • claude.ai and the Claude phone app: on the web, open Settings →
     Connectors → Add custom connector, name it MapleStats, and enter
     https://mcp.maplestats.danielstats.io/mcp. Then switch it on from the tools
     menu in a chat, on the web or in the phone app. Claude asks for approval
     before each call by default; every tool is read-only, so set them to
     always allow in the connector's tool permissions.
   • ChatGPT (web): turn on Settings → Security and login → Developer mode,
     then create a developer-mode app for a remote MCP server with the same
     address and No Authentication. Every tool is read-only, so ChatGPT
     should not ask to confirm calls. OpenAI documents this feature for the web.
   • A whole organization: on Claude Team or Enterprise, an Owner adds it once
     under Organization settings → Connectors → Add custom connector, and each
     member then connects it. On ChatGPT Business, Enterprise or Edu, an admin
     turns on Developer mode (Workspace Settings → Permissions & Roles →
     Connected Data), creates the app, and publishes it (Workspace settings →
     Apps → Drafts → Publish). The hosted server is shared and limits each
     client to 60 requests a minute, so a large organization should run its own
     copy.
   • VS Code: the same entry under a servers key, with "type": "http",
     in .vscode/mcp.json.

   {
     "mcpServers": {
       "maplestats": {
         "url": "https://mcp.maplestats.danielstats.io/mcp"
       }
     }
   }
   

2. Tell the user to restart or reload the client, then check that the
   search_tools tool is listed.

3. Only if the client cannot use remote servers, or the user wants
   everything kept on their own machine, run it locally instead: claude mcp add --scope user maplestats -- uvx maplestats-mcp
   (needs uv), or the equivalent uvx maplestats-mcp entry for other clients (see Install).

Each client gets 60 requests a minute. Your agent's tool calls (a search phrase, a table number)
reach the server and its host, Microsoft Azure (Canada Central). The code keeps
no log of them, but its in-memory cache can hold a search phrase or filter in a
key or a response until the entry expires or the server restarts. Check
Microsoft's terms and privacy statement; for full privacy, run it locally. What it logs:
FAQ. Other
clients: the Connect
page.

Teach your agent to use it well

skills/maplestats/SKILL.md is a portable
instruction file (Agent Skills format) for Claude Code, Codex, Cursor and
similar agents: start with plan_query, ask for the latest periods, read
the caveats, cite table, vector and release date, and run check_answer
before answering. Copy it into your agent's skills folder or project
instructions. It works with the hosted server and with a local one.

Clients for R, Python and Julia

To call the hosted server from a script, with no agent in between, use the
small clients in clients/r,
clients/python and
clients/julia. Each returns a data frame with
its citation. They are not on CRAN, PyPI or the Julia registry yet; each
README gives the command to install from GitHub.
docs/clients.md explains the design.

Install locally (optional)

Prefer to run it on your machine? It works over stdio with no account or key.

uvx maplestats-mcp                 # run without installing
uv tool install maplestats-mcp     # or install the command once (pip works too)
uv tool upgrade maplestats-mcp     # update

For the development version: uv tool install git+https://github.com/dsanchezp18/maplestats-mcp.git.
If you installed the command, use "command": "maplestats-mcp" with no
args in the JSON above. On Windows, make sure the directory where uv
installs tools is on PATH, and restart the client afterwards.

Using it

Tools are found through search rather than listed flat: call
search_tools with a plain-language query (English or French), then
call_tool with the name it returns.

{"name": "search_tools", "arguments": {"query": "consumer price index"}}
{"name": "call_tool", "arguments": {"name": "wds_search_cubes", "arguments": {"query": "consumer price index"}}}

plan_query turns a question into an ordered, multi-source plan, and
reproduce_code writes the R, Python, Stata or Julia script (or an Excel
Power Query) that fetches the same data straight from the source;
reproduce_workbook returns the rows as a formatted Excel workbook.
Before replying with figures, the assistant can call check_answer with the
StatCan and Bank of Canada figures it cites: it re-reads them from the source
and returns only the problems (a different value, a missed scale factor, a
newer period, another geography, an unadjusted series), each with a fix.
The calc_ tools do the arithmetic across series that assistants get wrong,
from StatCan and Bank of Canada series, and return the formula and every
input's citation with the result: calc_ratio (one series over another,
aligned by period, scale factors applied), calc_rank (places ranked for one
period, ties shared), calc_cagr (compound annual growth between two periods)
and calc_count_changes (how many times a series moved, such as policy rate
decisions). Mismatched frequencies or units are refused, not guessed.
Every tool accepts lang: "en"|"fr";
some sources only publish English content (for example Yukon's CKAN portal,
the World Bank's indicator definitions and the PMPRB), so there lang
changes the labels MapleStats adds, not the source's own text. Every response
has a provenance block: source, URL, query time, freshness and limits.
Through call_tool results are brief by default: values, periods, unit and
scale, the citation, status flags, caveats, limits, licence and URL, with a
list of six or more rows sent as one CSV text block ({"format": "csv", "csv": ...}) and the boilerplate (query time, cache flag, schema name,
freshness, the reproduce hint) left out. Pass detail="full" for every field
and the whole provenance block, rows as JSON objects. reproduce_code and
reproduce_workbook always read the full result.
docs://catalogue describes every module in both languages. The guided
prompts take lang too, and each docs://<module>/... resource has a French
twin at docs://<module>/fr/... (for example docs://statcan/fr/pieges).

To call the sources from Python without MCP, see docs/library.md.

What to watch for

MapleStats retrieves data directly from the original sources and returns
values as published. When a result is trimmed, scaled, cleaned or computed,
it says so in its provenance block or its notes; series values come
unscaled, with the scale factor beside them. When a source is down or blocks
the request, the tool returns an error, not a silent gap or a substitute
value.

The risk is in the use. An AI assistant can pick the wrong table, geography
or reference period, and the answers, summaries and analysis it writes are
AI-generated and can contain errors. For anything you would publish,
spot-check a few figures against the source's own site and use
reproduce_code to fetch them again outside the assistant. Publishers revise
their figures, so a value retrieved today can differ from an earlier one.

Each dataset keeps its own licence and attribution terms, shown in the
result's provenance; credit the publisher, not MapleStats. MapleStats is an
independent project, not affiliated with or endorsed by Statistics Canada,
the Bank of Canada, CMHC or any other data provider. It is provided as is,
depends on upstream services that can change or go offline, and is not
professional, legal or financial advice. Parts of the code and tests were
written with AI assistance; the discovery benchmark's questions were
written by one AI session and reviewed by a second, independent one, not yet
by a person
(tests/discovery_benchmark/REVIEW.md).

What it covers

457 tools in 89 modules. Run docs://catalogue for the full, bilingual list.

Other federal series (CRA, OSFI, ISED insolvency) are ordinary
open.canada.ca datasets, reachable with
ckan_search_datasets(portal="federal", fq="organization:<org>").

Not covered: CAPP's Statistics Handbook, Petrinex and Payments Canada were
not built, because their terms or download hosts do not permit automated
access. CanadaBuys, OpenParliament.ca and the Toronto Transit Commission's
own schedule download were removed for the same reason (the TTC schedule is
still served from Statistics Canada's national transit database). The City
of Whitehorse's open data files are not built: its terms bar commercial
reproduction without the City's written consent. The City of Toronto's
files (as opposed to its DataStore tables) are not read: its portal's robots.txt
disallows automated file downloads. The
City of Hamilton's portal is left out because it answers automated requests
with a Cloudflare challenge (Niagara Open Data did too until 2026-11-08, and is
now covered). The 2006-2016 census data tables and the 2016 Census Profile service were removed because Statistics Canada's www12 host answers automated clients with a bot challenge, 503 errors or timeouts (the 2021 profile and the WDS tables remain). Justice Laws (federal statutes and
regulations) is out of scope, because legislation text is not data this
server carries, and the Saskatchewan Bureau of Statistics' Provincial
Economic Accounts were not built: they are under Crown copyright, for
non-commercial reuse only, and the site's terms bar automated access. The
roadmap
records each decision.

Development

uv sync                          # install
uv run ruff check src tests scripts  # lint
uv run ruff format src tests scripts  # format
uv run pyright                   # type check
uv run pytest                    # unit tests (mocked, no network)

.\scripts\verify.ps1 runs that gate plus every scripts/smoke_test*.py
against the live APIs. The website is generated from the tool registry:
uv run python scripts/build_site.py writes build/site/. See
AGENTS.md
for the contributor guide and how to add a source module.

Hosting

MAPLE_TRANSPORT=http MAPLE_HOST=0.0.0.0 MAPLE_PORT=8000 uv run maplestats-mcp
serves HTTP instead of stdio. Docker Compose does the same in Docker, but the
image and docker-compose.yml set MAPLE_REQUIRE_AUTH=1, so the server refuses to
start until MAPLE_AUTH_TOKEN is set:
MAPLE_AUTH_TOKEN=<a long random string> docker compose up --build. Clients
then send that token as a bearer token. Docker is optional and unnecessary on
a personal computer. If the server is exposed beyond your machine, set
MAPLE_AUTH_TOKEN and keep MAPLE_REQUIRE_AUTH=1. GET /health reports uptime and version. GET /stats
is public, needs no token and reports calls per tool name and day, each tool's
p50 and p95 duration, and each upstream host's error counts and circuit-breaker
state (see MAPLE_USAGE_STATS and MAPLE_BREAKER below). After repeated
failures (timeouts, connection errors, 5xx answers, Cloudflare challenges) a
host is paused for a cooldown: its tools fail at once with an "unavailable"
error that says when to retry, instead of waiting for another timeout. The
docs://status resource lists the paused hosts.

License

MIT. Third-party notices are in THIRD_PARTY_NOTICES.md.

Security and conduct

Report a vulnerability privately through GitHub's
private vulnerability reporting;
see SECURITY.md. Changes are recorded in
CHANGELOG.md, and community expectations in
CODE_OF_CONDUCT.md.

Acknowledgments

MapleStats owes its architecture to
EcuDataMCP, the MCP server for
Ecuador's open data that I help maintain with
DweskZ and its other contributors. Its
approach to Canadian data owes much to the R developers who got there
first: Jens von Bergmann (mountainMath)
and his co-authors, including Dmitry Shkolnik
(dshkol), Thierry Warin (statcanR), Valentin
Lucet (rgovcan), and others. Thanks
to them, and to everyone who publishes Canadian data in the open.

For other ways to get Canadian data, see the
alternatives.