mcp-canada

<p align="center"> <h1 align="center">🍁 mcp-canada</h1> <p align="center"> <strong>MCP server giving AI agents structured access to Canadian federal, provincial, and municipal government data</strong> </p> <p align="center"> <a href="https://pypi.org/project/mcp-canada/"><img src="https://img.shields.io/pypi/v/mcp-canada?color=blue&label=PyPI" alt="PyPI"></a> <a href="https://pypi.org/project/mcp-canada/"><img src="https://img.shields.io/pypi/dm/mcp-canada?color=blue&label=downloads" alt="PyPI downloads"></a> <a href="https://github.com/ReyemTech/mcp-canada/actions/workflows/ci.yml"><img src="https://github.com/ReyemTech/mcp-canada/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="https://github.com/ReyemTech/mcp-canada/actions/workflows/ci.yml"><img src="https://img.shields.io/badge/coverage-96%25-brightgreen" alt="Coverage 96%"></a> <a href="https://github.com/ReyemTech/mcp-canada/stargazers"><img src="https://img.shields.io/github/stars/ReyemTech/mcp-canada?style=flat&logo=github" alt="GitHub stars"></a> <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.12+-blue" alt="Python 3.12+"></a> <a href="https://github.com/ReyemTech/mcp-canada/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT"></a> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-purple" alt="MCP Compatible"></a> <a href="https://github.com/jlowin/fastmcp"><img src="https://img.shields.io/badge/built%20with-FastMCP-orange" alt="Built with FastMCP"></a> </p> </p>

---

217 tools, ~87 prompts, and ~117 resources across 9 federal APIs + 5 provincial APIs + 2 municipal APIs + 1 local SQLite datastore — exchange rates, parliamentary data, product recalls, drug information, 80K+ open datasets, food nutrition data, real-time weather, immigration statistics, Ontario provincial data, Toronto municipal data, York Region ArcGIS Hub data, British Columbia CKAN + WFS geospatial data, Quebec Données Québec CKAN + ArcGIS IQA data, Alberta open data + AER energy + WMBappServices wildfire + AHSGIS health + 511 Alberta transport, and persistent local storage. All bilingual (English/French).

First ArcGIS Hub module — shared infrastructure in shared/arcgis_hub.py is reusable for future Canadian municipal modules (BC, Calgary, Edmonton, and other cities publishing via ArcGIS Hub). First OGC WFS module — BC introduces WFS 2.0 (OGC) support via shared/ogc.py, making WFS the third portal technology alongside CKAN and ArcGIS Hub. See docs://bc/wfs-query-guide for the CKAN→WFS two-step workflow.

Quick Start

# Auto-configure your platform (interactive)
uvx mcp-canada install

# Or name platforms directly
uvx mcp-canada install claude-desktop cursor vscode

Supports 14 platforms: Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Zed, Codex CLI, Gemini CLI, Amazon Q, OpenCode, Cline, Roo Code, Goose CLI, Junie CLI.

Manual Setup

<details> <summary>Claude Desktop</summary>

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-canada": {
      "command": "uvx",
      "args": ["mcp-canada"]
    }
  }
}

</details>

<details> <summary>Claude Code</summary>

claude mcp add mcp-canada -- uvx mcp-canada

</details>

<details> <summary>From Source</summary>

git clone https://github.com/reyemtech/mcp-canada.git
cd mcp-canada
uv run mcp-canada

</details>

Options

Flag	Description	Example
--transport	Transport protocol	--transport sse
--port	Port for SSE/HTTP	--port 8000
--modules	Load only specific modules	--modules bank_of_canada,recalls
--verbose	INFO-level logging	--verbose
--debug	DEBUG-level logging	--debug

Environment variable: MCP_CANADA_MODULES=bank_of_canada,recalls

Examples

See EXAMPLES.md for 23 cross-API intelligence scenarios — from tracing prairie drought to the Canadian dollar, to building pharmaceutical safety audits, to assembling MP accountability briefs, to joining data from multiple APIs in a single SQL query. Each example includes the exact prompt and tool chain you can run today.

How Discovery Works

With 217 tools, listing all of them would consume half an agent's context window. Instead, BM25 search lets agents find exactly what they need:

Agent: "What tools do you have for exchange rates?"

→ discover_tools("exchange rate CAD")
→ Returns: boc_get_exchange_rates, boc_get_observations

→ call_tool("boc_get_exchange_rates", {"currency": "USD", "recent": 3})
→ Returns: {"_meta": {...}, "data": [{"date": "2026-04-02", "value": 1.3918, ...}]}

Agents see 5 always-visible tools:

Tool	Purpose
discover_tools	BM25 natural language search across all tools
call_tool	Execute any discovered tool by name
list_modules	List available API modules with tool counts
plan_query	Plan a multi-step query across Canadian government data APIs
execute_batch	Run multiple tool calls in parallel with per-step error isolation

---

Modules

All tools accept lang: "en" | "fr" for bilingual support. Responses include a _meta envelope with source attribution and cache status. Click a module for its full tool, prompt, and resource catalog.

Module	Level	Tools	Prompts	Resources	Description
Meta / Discovery	—	5	—	—	Always-visible orchestration tools (discover_tools, call_tool, list_modules, plan_query, execute_batch)
Bank of Canada	Federal	8	5	7	Exchange rates, interest rates, commodity prices, inflation — Valet API
CKAN Open Data	Federal	7	5	7	80,000+ federal datasets — open.canada.ca
Drug Database	Federal	8	5	7	Drug products, ingredients, schedules — Health Canada DPD
IRCC Immigration	Federal	10	5	7	PR, study/work permits, Express Entry, asylum — IRCC Open Data
Nutrient File	Federal	8	5	7	Food nutrition data — Canadian Nutrient File
Open Parliament	Federal	10	5	7	Bills, MPs, votes, ballots, Hansard debates — Open Parliament API
Recalls & Safety	Federal	6	4	6	Food, vehicle, and health product recalls — Healthy Canadians
Statistics Canada	Federal	15	6	8	Time series, cube metadata, SDMX filtering — StatCan WDS
Weather	Federal	34	6	8	Conditions, climate, air quality, hydrology, marine, radar — MSC GeoMet
Alberta	Provincial	24	6	7	CKAN + AER energy + WMBappServices wildfire + AHSGIS health + 511 Alberta — open.alberta.ca
British Columbia	Provincial	20	6	7	CKAN + WFS geospatial — BC Data Catalogue
Ontario	Provincial	6	4	6	3,000+ provincial datasets — Ontario Open Data
Quebec	Provincial	18	6	7	Federated CKAN (139 orgs) — Données Québec
Toronto	Municipal	12	6	8	TTC, neighbourhoods, 311, RentSafe — Toronto Open Data
York Region	Municipal	27	5	8	4 ArcGIS Hub portals (York Region, Markham, Newmarket, Aurora)
Local Datastore	Local	6	4	6	SQLite persistence for cross-API SQL JOINs — ~/.mcp-canada/datastore.db
Total		217	~87	~117

---

Response Format

All tools return a consistent envelope:

{
  "_meta": {
    "source": {"api": "bank-of-canada-valet", "url": "https://..."},
    "cached": true,
    "lang": "en",
    "timestamp": "2026-04-04T12:00:00Z"
  },
  "data": [ ... ]
}

Errors return:

{
  "error": {
    "code": "INVALID_SERIES",
    "message": "Series 'FXXYZCAD' not found.",
    "suggestions": ["FXUSDCAD", "FXEURCAD"]
  }
}

Architecture

src/mcp_canada/
├── server.py              # FastMCP entry point, transport, module loading
├── shared/                # Cross-module utilities
│   ├── cache.py           # TTL-based in-memory cache (aiocache)
│   ├── envelope.py        # Response/error envelope (make_response/make_error)
│   ├── http.py            # Shared HTTP client with retry (tenacity)
│   ├── rate_limiter.py    # Per-source token bucket
│   └── i18n.py            # Bilingual error messages
├── meta/
│   └── list_modules.py    # list_modules meta-tool
└── modules/
    ├── bank_of_canada/    # 8 tools — Valet API
    ├── open_parliament/   # 10 tools — Parliament API
    ├── recalls/           # 6 tools — Healthy Canadians API
    ├── drug_database/     # 8 tools — Health Canada DPD
    ├── ckan/              # 7 tools — Open Data Portal
    ├── nutrient_file/     # 8 tools — Canadian Nutrient File
    ├── datastore/         # 6 tools — local SQLite persistence
    ├── ircc/              # 10 tools — IRCC Immigration Open Data
    ├── ontario/           # 6 tools — Ontario Open Data Catalogue
    ├── toronto/           # 12 tools — City of Toronto Open Data Portal
    ├── york_region/       # 27 tools — York Region ArcGIS Hub (4 portals)
    ├── british_columbia/  # 20 tools — BC Data Catalogue + WFS
    ├── quebec/            # 18 tools — Données Québec CKAN
    ├── alberta/           # 24 tools — open.alberta.ca CKAN + AER + WMB + AHSGIS + 511
    ├── statcan/           # 15 tools — Statistics Canada WDS + SDMX
    └── weather/           # 34 tools — MSC GeoMet OGC API
        ├── current/       # 5 tools — realtime conditions, forecast, alerts
        ├── climate/       # 7 tools — daily/monthly/normals/trends
        ├── aqhi/          # 3 tools — air quality health index
        ├── hydro/         # 5 tools — water levels, flow, flood risk
        ├── marine/        # 3 tools — marine forecasts, hurricane tracks
        ├── severe/        # 3 tools — radar, lightning, UV index
        ├── snow/          # 2 tools — snow depth, snow water equivalent
        ├── collections/   # 2 tools — collection browser and direct query
        └── summary/       # 4 tools — composite summary, extremes, growing season, degree days

Each module follows a 7-file pattern:

File	Purpose
__init__.py	Module name and description
constants.py	Base URL, rate limits, cache TTLs, API mappings
schemas.py	Pydantic v2 response models (always flat)
client.py	Async HTTP functions with caching and rate limiting
tools.py	@tool decorated MCP tool functions
prompts.py	@prompt functions — guided workflows + quick lookups
resources.py	@resource functions — catalogs, docs, templates

New modules are auto-discovered — drop a folder in modules/ and it registers via FileSystemProvider.

Development

# Install dependencies
uv sync

# Run tests (~2000 unit tests, ~15s)
uv run pytest

# Run integration tests against live APIs (~2min)
uv run pytest tests/integration/ -v -m integration --timeout=120

# Type check and lint
uv run pyright
uv run ruff check src/ tests/

# Coverage (must be ≥95%)
uv run pytest --cov=src/mcp_canada --cov-fail-under=95

Contributing

Each module is self-contained. To add a new API:

1. Create src/mcp_canada/modules/your_api/ with the 7-file pattern
2. Add colocated __tests__/ with unit tests
3. Add integration tests in tests/integration/test_tool_scenarios.py
4. Add a module doc in docs/modules/ and update the Modules table in this README

See CLAUDE.md for coding conventions.

Changelog

See CHANGELOG.md for version-by-version changes, or browse GitHub Releases.

Security

Found a vulnerability? Please do not open a public issue. Email contact@reyem.tech with details and reproduction steps. We support the latest minor version on PyPI.

Community

• Questions & ideas: GitHub Discussions
• Bugs & feature requests: GitHub Issues
• Contact: contact@reyem.tech

License

MIT — Reyem Tech

Star History

<a href="https://star-history.com/#ReyemTech/mcp-canada&Date"> <img src="https://api.star-history.com/svg?repos=ReyemTech/mcp-canada&type=Date" alt="Star History Chart"> </a>