MapleStats MCP

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 result carries its source.

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.

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://maplestats-mcp.onrender.com/mcp

   • Codex CLI: codex mcp add maplestats --url https://maplestats-mcp.onrender.com/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://maplestats-mcp.onrender.com/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://maplestats-mcp.onrender.com/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 the microdata tabulation tool or 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).

The first request after a quiet spell can take up to a minute; if your client reports the server as failed, retry a minute later. Each client gets 60 requests a minute, and the microdata tabulation tool is switched off there. Your agent's tool calls (a search phrase, a table number) reach the server and its host, Render. 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 Render's terms and privacy policy; for full privacy, run it locally. What it logs: FAQ. Other clients: the Connect page.

Related MCP server: Données Québec MCP

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. 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. 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

380 tools in 75 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), and the Saskatchewan GeoHub portal was removed. 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      # lint
uv run ruff format src tests     # 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 up --build does the same in Docker. 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.