Aryan-Jhaveri/mcp-statcan

📊 Statistics Canada API MCP Server

📝 Description

This project implements a Model Context Protocol (MCP) server that provides tools for interacting with Statistics Canada (StatCan) data APIs.

It allows LLMs or other MCP clients to access and retrieve Canadian statistical data in a structured way.

📑 Table of Contents

• 📝 Description
• 💬 Claude Chat Examples
• ✨ Features
• 🏗️ Project Structure
• 📥 Installation
• 🔧 Setup
• ⚠️ Known Issues
• 🚀 Usage Examples

💬 Claude Chat Examples

📊 Claude Dashboard Example

Effective Querying Tips

To get the most accurate results from Claude when using this Statistics Canada MCP server:

• Be Specific: Use precise, well-formed requests with exact details about the data you need
• Provide Context: Clearly specify tables, vectors, time periods, and geographical areas
• Avoid Typos: Double-check spelling of statistical terms and place names
• Structured Questions: Break complex queries into clear, logical steps
• Verify Results: Always cross-check important data against official Statistics Canada sources

⚠️ Warning: LLMs like Claude may occasionally create mock visualizations or fabricate data when unable to retrieve actual information. They might also generate responses with data not available in Statistics Canada to satisfy queries. Always verify results against official sources.

✨ Features

This server exposes StatCan API functionalities as MCP tools, including:

API Functionality

Cube Operations:

• Listing all available data cubes/tables — paginated, default 100 per page (offset/limit)
• Searching cubes by title — capped at max_results (default 25) with count message when more exist
• Retrieving cube metadata — summary=True (default) caps dimension member lists at 5 entries; use summary=False for all vectorIds
• Getting data for the latest N periods based on ProductId and Coordinate
• Getting series info based on ProductId and Coordinate
• Batch-fetching series info for multiple {productId, coordinate} pairs in a single call — paginated, with guidance for code-set fields
• Getting changed series data based on ProductId and Coordinate
• Listing cubes changed on a specific date
• Providing download links for full cubes (CSV/SDMX) (Discouraged)

Vector Operations:

• Retrieving series metadata by Vector ID
• Getting data for the latest N periods by Vector ID
• Getting data for multiple vectors by reference period range — paginated with guidance
• Getting bulk data for multiple vectors by release date range — paginated with guidance
• Getting changed series data by Vector ID
• Listing series changed on a specific date

Composite Operations:

• fetch_vectors_to_database — fetches multiple vectors and stores them in SQLite in a single call (preferred workflow for multi-series analysis)
• store_cube_metadata — fetches full cube metadata and stores it into _statcan_dimensions and _statcan_members SQLite tables; returns only a compact summary so the full member list never enters the context window. Use SQL to browse dimensions and look up vectorIds.

Database Functionality

The server uses a persistent SQLite database at ~/.statcan-mcp/statcan_data.db (configurable via --db-path flag or STATCAN_DB_FILE env var) for:

• Creating tables from API data and inserting rows in one step (create_table_from_data)
• Appending additional rows to existing tables (insert_data_into_table)
• Querying the database with SQL
• Viewing table schemas and listing available tables
• Dropping tables to free space (drop_table)

This allows for persistent storage of retrieved data and more complex data manipulation through SQL.

(Refer to the specific tool functions within src/api/ for detailed parameters and return types.)

🏗️ Project Structure

• src/: Contains the main source code for the MCP server.
• api/: Defines the MCP tools wrapping the StatCan API calls (cube_tools.py, vector_tools.py, composite_tools.py, metadata_tools.py).
• db/: Handles database interactions, including connection, schema, and queries.
• models/: Contains Pydantic models for API request/response validation and database representation.
• util/: Utility functions (e.g., coordinate padding).
• config.py: Configuration loading (e.g., database credentials, API base URL).
• server.py: MCP server definition and tool registration.
• __init__.py: Package initialization for src.
• pyproject.toml: Project dependency and build configuration.
• server.json: MCP Registry metadata.

📥 Installation

The only requirement is uv

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

uvx is bundled with uv and will automatically download and run statcan-mcp-server from PyPI on first use.

🔧 Setting Up Claude Desktop Configuration

Navigate to: Claude Desktop App → Settings (⌘ + ,) → Developer → Edit Config

{
  "mcpServers": {
    "statcan": {
      "command": "uvx",
      "args": ["statcan-mcp-server", "--db-path", "/your/path/to/.statcan-mcp/statcan_data.db"]
    }
  }
}

⚠️ Important: Pass --db-path with an absolute path. Claude Desktop alters the subprocess HOME environment variable, which can cause the default database path (~/.statcan-mcp/) to resolve incorrectly.

Restart the Claude Desktop app after saving.

Claude Code

WARNING: Untested yet

claude mcp add statcan --scope global -- uvx statcan-mcp-server

⚠️ Known Issues and Limitations

• "Unable to open database file" on Claude Desktop: Pass --db-path /Users/<you>/.statcan-mcp/statcan_data.db in your config args (see Setup). Claude Desktop alters the subprocess HOME env var, breaking default path resolution.
• SSL Verification: Currently disabled for development. Should be enabled for production use.
• Data Validation: Always cross-check your data with official Statistics Canada sources.
• Security Concerns: Query validation is basic; avoid using with untrusted input.
• Performance: Some endpoints may timeout with large data requests.
• API Rate Limits: The StatCan API may impose rate limits that affect usage during high-demand periods.