MapleStats MCP

MapleStats MCP

一个面向加拿大开放数据的 MCP 服务。

MapleStats MCP 让 AI Agent（Claude、Cursor 以及任何 MCP 客户端）通过一个 MCP 服务，以结构化方式访问加拿大开放数据：加拿大统计局（表格、人口普查、公共使用微观数据）、加拿大银行、CMHC、联邦机构，以及联邦、省、地区和市级开放数据门户，支持英语和法语。每条结果都附带其来源。

MapleStats MCP 通过一个 MCP 服务，让 AI Agent 以结构化方式访问加拿大开放数据，支持法语和英语。

项目愿景：docs/PROJECT_GUIDE.md。 数据源覆盖范围：docs/ROADMAP.md。 网站：https://maplestats.danielstats.io/。

最简单的方法：让你的 Agent 来配置

1. 复制这段提示词。
2. 将它粘贴到 Claude Code、Codex、Cursor 或任何能在你电脑上运行 命令的 Agent 中。
3. Agent 提示你重启时，重启它，然后请求数据。

将 MapleStats MCP 服务连接到此 Agent。按照 https://github.com/dsanchezp18/maplestats-mcp 中的设置步骤操作。

为配置服务的 Agent 提供的说明

默认使用托管服务：无需安装、无需账户，也无需密钥。

1. 将此远程（HTTP）MCP 服务注册为 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 和其他 mcpServers 客户端： 将以下条目添加到客户端的配置文件中（Cursor：~/.cursor/mcp.json；macOS 上的 Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json；Windows 上的 Claude Desktop：%APPDATA%\Claude\claude_desktop_config.json），并保留其中已有的服务。
   • claude.ai 和 Claude 手机应用： 在网页上打开 Settings → Connectors → Add custom connector，将其命名为 MapleStats，并输入 https://maplestats-mcp.onrender.com/mcp。然后在网页或手机应用的聊天中，从工具菜单启用它。默认情况下，Claude 会在每次调用前请求批准；所有工具都只读，因此请在连接器的工具权限中将它们设为始终允许。
   • ChatGPT（网页）： 打开 Settings → Security and login → Developer mode，然后为远程 MCP 服务创建一个开发者模式应用，填写相同地址并选择 No Authentication。所有工具都只读，因此 ChatGPT 应不会要求确认调用。OpenAI 提供了此网页功能的相关文档。
   • 整个组织： 在 Claude Team 或 Enterprise 中，由 Owner 在 Organization settings → Connectors → Add custom connector 下添加一次，然后每位成员再连接它。在 ChatGPT Business、Enterprise 或 Edu 中，管理员需启用 Developer mode（Workspace Settings → Permissions & Roles → Connected Data），创建应用并发布它（Workspace settings → Apps → Drafts → Publish）。托管服务是共享的免费实例，因此大型组织应运行自己的副本。
   • VS Code： 在 .vscode/mcp.json 中的 servers 键下添加相同条目，并设置 "type": "http"。

   {
     "mcpServers": {
       "maplestats": {
         "url": "https://maplestats-mcp.onrender.com/mcp"
       }
     }
   }
   

2. 告诉用户重启或重新加载客户端，然后检查是否列出了 search_tools 工具。

3. 只有当客户端无法使用远程服务，或用户想使用微观数据制表工具、或希望所有内容都保留在自己的电脑上时，才在本地运行：claude mcp add --scope user maplestats -- uvx maplestats-mcp（需要安装 uv），或者为其他客户端添加等效的 uvx maplestats-mcp 条目（参见安装）。

托管服务是免费实例，因此每次经过 15 分钟无活动后发出的第一个请求，都需要等待服务启动（实测 35 秒，最长可达一分钟）；如果客户端报告服务失败，请一分钟后重试。免费套餐的月运行时长可能会耗尽，此时端点会关闭，直到下个月 1 日才恢复；本地安装不受影响。每个客户端每分钟可发送 60 个请求，且微观数据制表工具在该实例上已关闭。Agent 的工具调用（搜索词、表格编号）会发送到服务及其托管平台 Render。代码不会记录这些调用，但其内存缓存可能会将搜索词或筛选条件保存在键或响应中，直到条目过期或服务重启。请查看 Render 的服务条款和隐私政策；如需完全保护隐私，请在本地运行。它会记录什么： 常见问题。其他 客户端请参阅连接页面。

本地安装（可选）

更倾向于在自己的机器上运行？它通过 stdio 工作，无需账号或密钥。

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

开发版本：uv tool install git+https://github.com/dsanchezp18/maplestats-mcp.git。 如果已安装该命令，请在上方的 JSON 中使用 "command": "maplestats-mcp"，且不添加 args。在 Windows 上，请确保 uv 安装工具的目录位于 PATH 中，并在之后重启客户端。

使用方法

工具通过搜索来查找，而不是以平铺列表的形式呈现：使用自然语言查询（英语或法语）调用 search_tools，然后使用它返回的名称调用 call_tool。

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

plan_query 会将问题转化为有序的多来源计划；reproduce_code 会编写 R、Python、Stata 或 Julia 脚本（或 Excel Power Query），以便直接从来源获取相同数据； reproduce_workbook 会将行数据以格式化的 Excel 工作簿形式返回。每个工具都接受 lang: "en"|"fr"； 有些来源仅发布英文内容（例如 Yukon 的 CKAN 门户、 World Bank 的指标定义和 PMPRB），因此此处的 lang 会改变 MapleStats 添加的标签，而非来源自身的文本。每个响应 都包含一个 provenance 区块：来源、URL、查询时间、时效性和限制。 docs://catalogue 以两种语言介绍每个模块。引导式 提示词也接受 lang，每个 docs://<module>/... 资源都有对应的法语版本，路径为 docs://<module>/fr/...（例如 docs://statcan/fr/pieges）。

注意事项

MapleStats 直接从原始来源获取数据，并按发布时的数值返回。 如果结果经过截取、缩放、清理或计算，会在 provenance 区块或备注中 说明；序列数值未经缩放，旁边会注明缩放因子。如果来源不可用或阻止 请求，工具会返回错误，而不会无声地漏掉数据或提供替代 数值。

风险在于数据的使用。AI 助手可能会选错表格、地理区域 或参考期；生成的答案、摘要和分析 也可能出错。对于任何准备发布的内容，请对照来源网站抽查 几项数据，并使用 reproduce_code 在助手之外重新获取数据。发布方会修订 数据，因此今天获取的数值可能与之前的数值不同。

每个数据集都有自己的许可和署名条款，这些信息会显示在结果的 provenance 中；请注明发布方，而非 MapleStats。MapleStats 是一个 独立项目，与 Statistics Canada、Bank of Canada、CMHC 或任何其他数据提供方 均无关联，也未获得其认可。本项目按现状提供， 依赖可能发生变化或下线的上游服务，不构成专业、法律或财务建议。部分代码和测试 是在 AI 的协助下编写的；发现基准测试的问题由一次 AI 会话编写，并由另一个独立的会话审阅，尚未经过人工审核 （tests/discovery_benchmark/REVIEW.md）。

覆盖范围

75 个模块中共有 380 个工具。运行 docs://catalogue 查看完整的双语列表。

领域	工具前缀	涵盖内容
加拿大统计局	wds_、sdmx_、sdmx_space_、rdaas_、cimt_、statcan_*	表格和序列、额外的 SDMX 空间（能源信息、共享数据）、分类体系、2001–2021 年人口普查概况、公共使用微观数据（代码簿、加权表格）、按商品划分的商品贸易（CIMT）、开放数据库（LODE）、《The Daily》、增量文件、指标、调查、人口普查地理信息
加拿大银行	boc_	Valet 序列、分组、观测值
加拿大抵押贷款和住房公司（CMHC）	cmhc_、cmhc_dt_	住房市场信息门户和 Excel 数据表
联邦机构	eccc_、eccc_coverages_、eccc_datamart_、ised_*、gazette_、tc_recalls_、recalls_、cdc_、cfia_、fcac_、finance_、cihi_、phac_infobase_、hc_*、pmra_、pmprb_、gc_infobase_、cer_、nrcan_*、dfo_iwls_、cgc_、nfd_、ircc_*、cbsa_、cbsa_tariff_、pbo_、competition_bureau_、elections_results_、elections_financial_returns_、cra_digital_economy_registry_、earthquakes_、borealis_、isc_	天气、气候和网格化气候预测、污染物排放和温室气体排放（NPRI、GHGRP、NAPS）、企业和知识产权、法规、召回、乳制品、动物疾病、消费者银行业务、联邦和省级财政表格、卫生、药品、天然健康产品、医疗器械、不良反应、农药、支出、能源、矿产生产、海洋、谷物、林业、移民、边境等待时间、关税税率、预算、合并、选举、地震、大学图书馆数据表、第一民族概况、登记人口和饮用水公告
野地火灾	cwfis_、nrcan_nbac_、ab_wildfire_	NRCan 的加拿大野地火灾信息系统（卫星热点、火灾危险、气象站）、烧毁区域，以及 Alberta Wildfire 的实时火情
电力	electricity_ontario_、electricity_quebec_、oeb_	IESO（安大略省）的需求、发电量和价格；Hydro-Québec 的需求、发电量和贸易（CC BY-NC 4.0：注明来源为 Hydro-Québec，仅限非商业用途）；安大略省能源委员会数据集
议会和民选官员	ourcommons_、senate_、represent_	国会议员及其职务、政党席位、内阁、参议院投票；通过 Open North 的 Represent 查询邮政编码对应的民选官员和选区（非官方）
省级机构	aer_、bcgw_、bc_stats_、bc_env_、bc_lobbyists_、drivebc_、ab_economic_、ab_opendata_、isq_、nl_stats_、yukon_stats_、nwt_stats_、elections_provincial_、on_fir_	阿尔伯塔能源监管机构、BC 地理信息仓库、BC Stats Excel 表格、BC 环境监测（空气质量、积雪、地下水、河流流量）、BC 游说者登记册、DriveBC 道路事件、阿尔伯塔经济仪表板、Open Alberta 文件、魁北克统计研究所、纽芬兰与拉布拉多、育空和西北地区统计局、省级大选结果（魁北克、阿尔伯塔、不列颠哥伦比亚、萨斯喀彻温、曼尼托巴）、安大略省市政财务信息申报表（涵盖每个市镇的所有附表，始于 2000 年）
住房（仅提供链接）	crea_	CREA 的 MLS® 房价指数链接、发布时间和条款；不提供数值，因为 CREA 的条款仅允许私人、非商业分析
国际	worldbank_、bis_	世界银行加拿大及同类国家的世界发展指标（CC BY 4.0）；国际清算银行统计数据：政策利率、偿债比率、信贷、房价、银行业和支付统计数据（注明来源即可免费复用）
开放数据门户	ckan_、arcgis_hub_、socrata_ + portal	联邦、省级、地区和市政目录（*_list_portals 会列出每个目录）
其他市政数据	opendatasoft_vancouver_、nl_opendata_、eps_、ets_、epcor_	温哥华、纽芬兰与拉布拉多、埃德蒙顿警务、公共交通和水质
公共交通时刻表	transit_ + agency	STM（公交车）、OC Transpo、Calgary Transit、VIA Rail、GO Transit、UP Express、BC Transit 各系统，以及 Données Québec 列出的魁北克交通网络（exo、RTC、STL、STS 等）的静态 GTFS 时刻表；此外还有加拿大统计局 2025 年加拿大公共交通网络数据库中的其他机构：站点、线路、计划出发时间、每小时班次频率
其他联邦系列（CRA、OSFI、ISED 破产数据）都是普通的
open.canada.ca 数据集，可通过
ckan_search_datasets(portal="federal", fq="organization:<org>") 访问。

未涵盖的内容：未构建 CAPP 的《Statistics Handbook》、Petrinex 和 Payments Canada，因为它们的条款或下载主机不允许自动访问。出于同样的原因，CanadaBuys、OpenParliament.ca 和多伦多交通委员会（TTC）自己的时刻表下载均已移除（TTC 时刻表仍由 Statistics Canada 的全国交通数据库提供），萨斯喀彻温省 GeoHub 门户也已移除。2006—2016 年人口普查数据表和 2016 Census Profile 服务已移除，因为 Statistics Canada 的 www12 主机会向自动化客户端返回机器人验证、503 错误或超时（2021 年人口概况和 WDS 数据表仍然保留）。Justice Laws（联邦法规和规章）不在范围内，因为该服务不提供法律文本数据；萨斯喀彻温省统计局的 Provincial Economic Accounts 也未构建：这些数据受 Crown 版权保护，仅允许非商业性再利用，且网站条款禁止自动访问。 路线图 记录了每项决定。

开发

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 会运行该检查，以及针对在线 API 的所有 scripts/smoke_test*.py。 网站由工具注册表生成： uv run python scripts/build_site.py 会写入 build/site/。有关贡献者指南以及如何添加源模块，请参阅 AGENTS.md。

托管

MAPLE_TRANSPORT=http MAPLE_HOST=0.0.0.0 MAPLE_PORT=8000 uv run maplestats-mcp 会通过 HTTP 而非 stdio 提供服务；docker compose up --build 则会在 Docker 中执行相同操作。Docker 是可选的，在个人电脑上并非必需。如果将服务暴露到本机之外，请设置 MAPLE_AUTH_TOKEN 并将 MAPLE_REQUIRE_AUTH=1 保持启用。GET /health 会报告运行时间和版本。GET /stats 是公开的，无需令牌，会报告按工具名称和日期统计的调用次数、每个工具的 p50 和 p95 耗时，以及每个上游主机的错误计数和断路器 状态（见下文的 MAPLE_USAGE_STATS 和 MAPLE_BREAKER）。发生多次故障（超时、连接错误、5xx 响应、Cloudflare 验证）后，主机 会暂停一段冷却时间：其工具会立即失败，并返回说明何时可重试的“不可用”错误，而不会继续等待另一次超时。docs://status 资源会列出已暂停的主机。

公共端点运行在 Render 免费套餐上：内存约为 512 MB，无请求 15 分钟后进入休眠，整个工作区每月共享 750 个实例小时，由其中的所有免费服务共用。2026-10-24 时，该 工作区已使用其中 659 个小时。Render 的 10 月 19 日至 24 日日志显示， maplestats-mcp 有 91% 的时间在运行，这是因为真实 MCP 客户端每隔几分钟连接一次而保持唤醒，并非因为有定时探测器；同一工作区中的另一个免费服务则在较长时段内大约每 15 分钟唤醒一次。按此速度，实例小时会在月底前耗尽，届时工作区中的所有免费服务都会停止，直到 1 日。自 2026-10-24 起，聊天演示 （chat/render.yaml）和另一个服务分别运行在各自的工作区中，因此本服务可独享这 750 个小时。

环境变量	默认值	用途
MAPLE_TRANSPORT	stdio	本地客户端使用 stdio，托管时使用 http
MAPLE_HOST / MAPLE_PORT	127.0.0.1 / 8000	HTTP 绑定地址
MAPLE_AUTH_TOKEN, MAPLE_REQUIRE_AUTH	未设置，0	/mcp 上必需的 Bearer 令牌；若值为 1，未设置令牌时拒绝启动。docker-compose.yml 默认将 MAPLE_REQUIRE_AUTH 设为 1
MAPLE_RATE_LIMIT_REQUESTS / MAPLE_RATE_LIMIT_WINDOW_SECONDS	120 / 60	每个客户端的速率限制
MAPLE_MAX_CONCURRENT_REQUESTS	8	并发请求上限；超出的请求等待 5 s，然后收到 503
MAPLE_SSL_CERTFILE / MAPLE_SSL_KEYFILE	未设置	进程内 TLS
MAPLE_TRUST_PROXY_HEADERS	0	根据 X-Forwarded-For 限制速率；仅在位于会设置此标头的代理后时启用
MAPLE_TRUSTED_PROXY_HOPS	1	会向 X-Forwarded-For 追加地址的代理数；从右侧起按此数量读取客户端地址
MAPLE_ALLOWED_ORIGINS	项目网站、localhost	/mcp 上允许的浏览器来源（以逗号分隔，支持 *. 和 :* 通配符）；其他来源会收到 403，没有 Origin 的客户端则允许访问
MAPLE_CACHE_MAX_ENTRIES	2000	每个 TTL 缓存桶的响应缓存大小
MAPLE_CACHE_MAX_MB	128	所有缓存桶合计的响应缓存估算内存上限
MAPLE_PARSE_WORKERS / MAPLE_PARSE_TIMEOUT_SECONDS	4 / 60	用于解析 Excel 和 CSV 文件的线程数，以及单次解析可用时长
MAPLE_TOOL_TIMEOUT_SECONDS	120	工具调用可运行的最长时间
MAPLE_BREAKER	1	连续失败后暂停向上游主机发送请求；0 则发送每个请求
MAPLE_BREAKER_FAILURES / MAPLE_BREAKER_WINDOW_SECONDS / MAPLE_BREAKER_COOLDOWN_SECONDS	5 / 300 / 60	在时间窗口内连续失败达到此次数时暂停主机，以及发送一次探测请求前的等待时间
MAPLE_PUMF_TABULATE	1	0 会隐藏 statcan_pumf_tabulate（此工具会下载完整的 PUMF ZIP 文件）；搜索、列表和代码本仍可用
MAPLE_PUMF_CACHE_DIR, MAPLE_PUMF_CACHE_MAX_GB	系统临时目录，5	下载的微观数据缓存；托管时请使用持久卷
MAPLE_CLIENT_IP_HEADER	未设置	外层代理设置的、表示调用方自身地址的标头（Cloudflare 的 CF-Connecting-IP）；启用 MAPLE_TRUST_PROXY_HEADERS 时用于每客户端速率限制；仅当所有请求都经过该代理时才设置
MAPLE_DUCKDB_MEMORY_LIMIT	未设置	DuckDB 查询下载文件（专利、开放数据库、微观数据）时的内存限制，例如 256MB；超出后 DuckDB 会将数据溢写到临时文件夹。小型托管实例请设置此项
MAPLE_LODE_CACHE_DIR, MAPLE_LODE_CACHE_MAX_GB	系统临时目录，3	解压 StatCan 开放数据库（LODE）档案的位置及大小上限（优先移除最近最少使用的文件）；托管时请使用持久卷
MAPLE_LODE_MAX_DOWNLOAD_MB	300	单次调用可下载的开放数据库档案最大大小；0 会关闭下载
MAPLE_IP_HORIZONS_CACHE_DIR, MAPLE_IP_HORIZONS_CACHE_MAX_GB	系统临时目录，3	CIPO 专利表缓存
MAPLE_CBSA_TARIFF_CACHE_DIR	系统临时目录	以 Parquet 格式保存的海关关税版本（每个小于 1 MB，保留最新的 12 个）
MAPLE_ON_FIR_CACHE_DIR, MAPLE_ON_FIR_CACHE_MAX_MB	系统临时目录，500	以 Parquet 格式保存的安大略省 FIR 年份数据（每个约 3 MB）；托管时请使用持久卷
MAPLE_EXPORT_DIR	Downloads 文件夹（若不存在则使用主文件夹）	本地服务上 reproduce_workbook 保存 Excel 工作簿的位置
MAPLE_SEARCH, MAPLE_SEMANTIC_DIR	bm25，未设置	hybrid 将 BM25 与本地 multilingual-e5-small 索引融合（需要 [semantic] 额外依赖和 python -m maplestats_mcp.shared.semantic build）；默认关闭，参见 tests/discovery_benchmark/phase2.md
MAPLE_RESPONSE_MAX_BYTES	200000	单个工具结果的字节数预算（最低为 10,000）；较大的结果会裁剪其中最大的列表，provenance.limits 会说明保留了哪些内容以及如何获取其余内容
MAPLE_USAGE_STATS	1	在内存中按工具名称和 UTC 日期统计调用次数与时长，并按主机统计上游错误（绝不记录参数或客户端地址），并通过公开的 /stats 路由提供统计数据；0 会关闭这两项功能
MAPLE_DELTA_MAX_SCAN_MB / MAPLE_DELTA_MAX_SCAN_SECONDS	400 / 75	单次 statcan_delta_read_table 调用可流式读取的 Delta 文件数据量（秒数比工具超时时间少 30）
MAPLE_DELTA_INDEX_DIR	系统临时目录	保存的 Delta 文件续传位置（每天占用几 MB）；设为 off 时仅保存在内存中

许可证

MIT。第三方声明见 THIRD_PARTY_NOTICES.md。

安全与行为准则

请通过 GitHub 的 私密漏洞报告 私下报告漏洞；详见 SECURITY.md。变更记录见 CHANGELOG.md，社区行为准则见 CODE_OF_CONDUCT.md。

致谢

MapleStats 的架构得益于 EcuDataMCP——面向 厄瓜多尔开放数据的 MCP 服务，我与 DweskZ 及其他贡献者共同维护该项目。它 对加拿大数据的处理方式，很大程度上借鉴了先行一步的 R 开发者： Jens von Bergmann（mountainMath） 及其合著者，包括 Dmitry Shkolnik （dshkol）、Thierry Warin（statcanR）、Valentin Lucet（[rgovcan](https://github.com/VLucet/rgovcan））以及其他人。感谢 他们，也感谢所有以开放方式发布加拿大数据的人。

如需了解获取加拿大数据的其他方式，请参阅 替代方案。