统计数据访问服务器

Schwaizer BFS MCP Server

An unofficial MCP server for accessing Swiss Federal Statistical Office (BFS) data

This is a community project by Schwaizer and is not an official implementation by the Swiss government.

关于Schwaizer

塑造瑞士人工智能的未来

通过负责任的人工智能采用，赋予瑞士企业和社会权力。

Schwaizer成立于2025年，是一家非营利组织，致力于在瑞士加速负责任地采用人工智能。

网站：https://www.schwaizer.ch

概述

Schwaizer BFS MCP服务器通过模型上下文协议（MCP）提供对瑞士联邦统计局（Bundesamt für Statistik/Office fédéral de la Statistics）统计数据的程序化访问。

此服务器与三个BFS API集成：

• PXWEB API -API主要统计数据，数据集全面
• 瑞士国家统计局（SSE）API -用于时间序列数据的基于SDMX的现代API
• API大坝 -用于搜索和发现数据集的数据资产管理目录

特性

• 🔍 搜索数据集 按关键字、主题和空间划分
• 📊 检索统计数据 具有灵活的过滤选项
• 🌍 多语言支持 （德语、法语、意大利语、英语）
• 📈 时间序列数据 通过瑞士统计资源管理器API访问
• 🗂️ 浏览目录 包含21个统计主题
• 🔧 元数据探索 了解数据集结构
• ⚡ 限速处理 自动重试
• 📝 结构化日志记录 用于调试

安装

先决条件

• Node.js 20.0.0或更高版本
• npm或pnpm

再进行

npm install

配置

复制示例环境文件：

cp .env.example .env

编辑 .env 自定义设置（可选）：

# Logging level (debug, info, warn, error)
LOG_LEVEL=info

# Optional: Rate limiting
BFS_REQUEST_DELAY=0
BFS_MAX_RETRIES=3

用法

运行服务器

npm start

服务器通过stdio运行，可以与任何兼容MCP的客户端集成。

可用工具

目录工具

search_datasets

在BFS目录中搜索统计数据集。

参数：

• language （可选）：结果语言（de、fr、it、en）-默认值：en
• query （可选）：在标题和描述中查找的搜索词
• theme （可选）：按主题筛选（prodima编号）
• spatialDivision （可选）：按空间划分级别过滤
• publishingYearStart （可选）：按发布年份开始筛选
• publishingYearEnd （可选）：按发布年末筛选
• limit （可选）：最大结果（1-1000）-默认值：50

例子：

{
  "language": "en",
  "query": "students",
  "theme": 900212,
  "limit": 10
}

list_themes

列出所有可用的统计主题（类别）。

参数：

• language （可选）：主题名称的语言-默认值：en

退货： 包含prodima编号和代码的21个主题列表。

get_dataset_info

获取特定数据集的详细信息。

参数：

• numberBfs （可选）：BFS编号（例如，“px-x-1502040100_131”）
• numberAsset （可选）：资产编号
• language （可选）：结果语言-默认值：en

注： 提供其中之一 numberBfs 或 numberAssetPXWEB和SSE数据集的BFS编号不同。

数据工具

get_statistical_data

从PXWEB API检索统计数据。

参数：

• numberBfs （必填）：数据集的BFS编号
• language （可选）：结果语言-默认值：en
• query （可选）：维度过滤器作为键值对
• format （可选）：响应格式（json-stat、json、csv）-默认：json-stat

例子：

{
  "numberBfs": "px-x-1502040100_131",
  "language": "en",
  "query": {
    "Jahr": ["40", "41"],
    "Studienstufe": ["2", "3"]
  }
}

get_sse_data

从瑞士统计资源管理器API检索时间序列数据。

参数：

• numberBfs （必填）：SSE数据集标识符（例如“DF_LWZ_1”）
• language （可选）：结果语言-默认值：en
• query （可选）：维度过滤器
• startPeriod （可选）：起始期（例如“2020”）
• endPeriod （可选）：结束期（例如“2023”）

注： SSE数据集的BFS编号与PXWEB数据集不同。

例子：

{
  "numberBfs": "DF_PASTA_552_MONTHLY",
  "language": "en",
  "query": {
    "FREQ": "M",
    "ACCOMMODATION_TYPE": ["552001"],
    "COUNTRY_ORIGIN": ["CH", "AUSL"]
  },
  "startPeriod": "2020",
  "endPeriod": "2023"
}

元数据工具

get_dataset_metadata

获取PXWEB数据集的完整元数据结构。

参数：

• numberBfs （必填）：数据集的BFS编号
• language （可选）：标签语言-默认值：en

退货： 包含所有代码和值的完整尺寸结构。

get_sse_metadata

获取Swiss Stats Explorer数据集的元数据。

参数：

• numberBfs （必填）：SSE数据集标识符
• language （可选）：标签语言-默认值：en

get_dataset_dimensions

获取可用维度的简化视图以进行过滤。

参数：

• numberBfs （必填）：数据集的BFS编号
• language （可选）：标签语言-默认值：en

退货： 带有示例值的尺寸代码，便于快速参考。

典型工作流程

1.发现数据集

// Search for datasets about students
search_datasets({
  "query": "students",
  "language": "en",
  "theme": 900212  // Education theme
})

2.探索数据集结构

// Get metadata to understand available dimensions
get_dataset_metadata({
  "numberBfs": "px-x-1502040100_131",
  "language": "en"
})

3.检索数据

// Get filtered data
get_statistical_data({
  "numberBfs": "px-x-1502040100_131",
  "language": "en",
  "query": {
    "Jahr": ["40", "41"],  // Years 2020/21, 2021/22
    "Geschlecht": ["0", "1"]  // All genders
  }
})

示例用例：人口统计分析

本节演示了查找和检索特定人口统计数据的完整工作流程。

目标： 计算2020-2024年苏黎世（ZH）、伯尔尼（BE）和沃州（VD）的永久居民总人口。

步骤1：搜索相关数据集

首先，搜索与州级人口相关的数据集。

search_datasets({
  "language": "en",
  "query": "population",
  "spatialDivision": "Cantons"
})

这将返回一个数据集列表。我们确定 "px-x-0102010000_102" （“2010-2024年按州、性别、婚姻状况和年龄分列的永久居民和非永久居民人口”）是最相关的。

步骤2：获取数据集元数据

接下来，获取元数据以了解数据集的结构，并找到过滤代码。

get_dataset_metadata({
  "numberBfs": "px-x-0102010000_102",
  "language": "en"
})

从元数据中，我们识别出以下代码：

• 个州: ZH, BE, VD
• 群体类型: 1 （常住人口）
• 性: -99999 （总计）
• 婚姻状况: -99999 （总计）
• 年龄: -99999 （总计）

步骤3：检索数据

最后，使用代码查询特定的数据点。

get_statistical_data({
  "language": "en",
  "numberBfs": "px-x-0102010000_102",
  "query": {
    "Jahr": ["2020", "2021", "2022", "2023", "2024"],
    "Kanton": ["ZH", "BE", "VD"],
    "Bevölkerungstyp": "1",
    "Geschlecht": "-99999",
    "Zivilstand": "-99999",
    "Alter": "-99999"
  },
  "format": "json"
})

第四步：分析结果

查询返回以下数据，然后可用于分析或可视化。

此工作流程演示了如何高效地浏览BFS数据目录并检索精确的数据进行分析。

BFS主题

BFS将数据分为21个主题领域：

速率限制

BFS PXWEB API具有速率限制。如果您遇到HTTP 429错误：

1. 增加请求之间的延迟：设置 BFS_REQUEST_DELAY 在 .env
2. 查询具体维度：按特定维度过滤，而不是请求所有数据
3. 使用较小的数据集：将大型查询分解为较小的块

API 文档

PXWEB API

• 基本URL: https://www.pxweb.bfs.admin.ch/api/v1
• 文档： PXWEB API指南

瑞士统计局（SSE）

• 基本URL: https://stats.swiss/api/v1
• 格式：基于SDMX的XML响应

API大坝

• 基本URL: https://dam-api.bfs.admin.ch/hub/api
• 用途：数据集目录和元数据

错误处理

服务器为常见问题提供明确的错误消息：

• 404未找到：数据集不存在-检查BFS编号
• 429请求太多：超出速率限制-增加延迟或减小查询大小
• 400错误请求：查询参数无效-请检查维度代码和值
• 未找到记录：查询筛选器与任何数据都不匹配-调整筛选器或时间段

发展

项目结构

schwaizer-bfs-mcp/
├── src/
│   ├── index.js              # MCP server entry point
│   ├── config.js             # Configuration loader
│   ├── api/                  # API clients
│   │   ├── pxweb-client.js   # PXWEB API
│   │   ├── sse-client.js     # Swiss Stats Explorer
│   │   └── dam-client.js     # DAM catalog
│   ├── tools/                # MCP tool implementations
│   │   ├── catalog-tools.js  # Search & discovery
│   │   ├── data-tools.js     # Data retrieval
│   │   └── metadata-tools.js # Metadata access
│   └── utils/                # Utilities
│       ├── logger.js         # Logging
│       └── formatting.js     # Helpers
├── tests/                    # Test files
├── docs/                     # Documentation
├── .env.example              # Environment template
├── package.json              # Dependencies
└── README.md                 # This file

脚本

• npm start -启动MCP服务器
• npm run dev -从文件更改时自动重新加载开始
• npm test -运行测试（实施时）
• npm run lint -运行ESLint
• npm run format -使用Prettier格式化代码

贡献

欢迎投稿！请随时提交问题或拉取请求。

许可证

MIT许可证-有关详细信息，请参阅许可证文件

免责声明

这是一个非官方的社区项目，不隶属于瑞士联邦统计局（BFS/OFS/UST/UFS）或得到其认可。

资源

• BFS官方网站
• BFS数据目录
• 瑞士统计探索者
• 模型上下文协议
• Schwaizer组织

支持

有关问题和疑问，请在项目的GitHub存储库上打开问题。

内置于❤️ 由Schwaizer为瑞士人工智能社区撰写