🇨🇦 Bank of Canada Valet MCP Server

An MCP server that gives LLM agents (Claude, and any other MCP-compatible client) live access to Canadian economic and financial data through the Bank of Canada Valet API — exchange rates, interest rates, inflation series, and thousands more.

The Valet API is free and requires no API key, so this server runs out of the box.

Ask "What's the latest USD/CAD exchange rate?" or "Chart CORRA over the last month" and the agent pulls the numbers straight from the source.

---

Why this exists

Large language models don't know today's exchange rate — their training data is frozen in the past. MCP closes that gap by letting a model call live tools. This server is a small, focused, production-shaped example of that pattern: clean tool design, input validation, actionable errors, and tests.

Features

• 5 well-scoped tools covering discovery → metadata → data retrieval
• No API key — the Valet API is public
• Dual output — human-readable Markdown or structured JSON, per call
• Search + pagination over the large series/group catalogue
• Multi-series comparison — pull several series side by side in one call
• Agent-friendly errors — every failure explains what to try next
• Typed & validated — Pydantic Field constraints on every parameter
• Tested — offline unit tests, no network needed for CI

Tools

Tool	What it does
boc_list_series	Search / list the available data series (start here)
boc_list_groups	Search / list curated groups of related series
boc_get_series_info	Fetch metadata (label, description) for one series
boc_get_observations	Core: get data points for one or more series, by date range or most-recent
boc_get_group_observations	Get every series in a group in a single call

Architecture

src/boc_valet_mcp/
├── server.py       # MCP tool definitions (the interface agents see)
├── client.py       # Async httpx client + centralized, actionable errors
└── formatting.py   # Markdown / JSON rendering (shared by every tool)

The separation keeps each layer testable: tools stay thin, HTTP concerns live in one place, and presentation logic is unit-tested offline against representative payloads.

Quickstart

git clone https://github.com/Chatusvi-Karnati/boc-valet-mcp.git
cd boc-valet-mcp
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .

Run it directly (it speaks MCP over stdio):

boc-valet-mcp

Inspect it interactively

The MCP Inspector is the fastest way to click through the tools:

npx @modelcontextprotocol/inspector boc-valet-mcp

Use it with Claude Desktop

Add this to your claude_desktop_config.json (see examples/):

{
  "mcpServers": {
    "bank-of-canada": {
      "command": "boc-valet-mcp"
    }
  }
}

Restart Claude Desktop and ask it something like "Compare the USD/CAD and EUR/CAD rates over the past week."

Example

Calling boc_get_observations with series_names="FXUSDCAD", recent=1:

**Series:**
- `FXUSDCAD` — US dollar to Canadian dollar daily exchange rate

| Date       | FXUSDCAD |
|------------|----------|
| 2024-06-03 | 1.3654   |

_1 observation(s)._

Development

pip install -e ".[dev]"
pytest              # run the test suite
ruff check .        # lint

How it was built

Designed and built following Anthropic's MCP server best practices — comprehensive tool coverage, readOnly/idempotent annotations, Pydantic-validated inputs, and error messages written for an agent audience. Developed with an AI-assisted workflow using Claude Code.

License

MIT — see LICENSE.

Acknowledgements

Data is provided by the Bank of Canada Valet API. This project is not affiliated with or endorsed by the Bank of Canada. Please review the Bank of Canada's terms of use for the data.