ILO Labour Statistics (ILOSTAT): unemployment, wages, informality

国际劳工组织劳工统计（ILOSTAT）— MCP 服务

🇧🇷 阅读葡萄牙语版

这是一个公开托管、优先保证来源可追溯的 MCP 服务，提供**国际劳工组织（ILO）**的统计数据，即 ILOSTAT 数据库——无需安装、无需账户、无需 API 密钥。将 MCP 客户端连接到托管端点，即可按国家、年份、性别和年龄查询失业、就业、工资、工作时间及其他劳工指标。服务运行于 Cloudflare Workers，使用 Streamable HTTP，并连接官方 ILOSTAT SDMX REST API。

独立项目。 这是一个由社区构建的非官方客户端，用于访问 ILO 的公开 ILOSTAT API，与国际劳工组织无关联，也未获其认可。 数据版权归 ILO 所有，并遵循 CC BY 4.0 许可；请参阅数据许可与署名。

每个响应都包含一个来源信息块（来源 URL、数据版本、真实检索时间戳、许可协议、ILO 引用）——提供带有审计线索的精确数据，而非从训练数据中猜出的数字。

🇧🇷 葡萄牙语版。 面向 ILO 劳动力市场统计数据的远程托管 MCP 服务（无需安装、无需账户、无需密钥），可按国家、年份、性别和年龄查询失业、就业、工资、工时和非正规就业数据，直接在 Claude、ChatGPT 或任何 MCP 客户端中使用；每个响应都提供来源信息和引用： 葡萄牙语版 README。

它能回答的问题

用通俗语言，在 MCP 客户端中由助手选择工具和筛选条件：

• “自 2015 年以来，巴西的失业情况发生了什么变化？”（ilo_get_data）
• “比较巴西、墨西哥和南非的青年失业情况。”（ilo_compare_countries）
• “性别工资差距有多大，ILO 在哪里发布相关数据？” （ilo_search_indicators → ilo_get_data）
• “印度的非正规就业占比是多少？”（ilo_search_indicators → ilo_get_data）
• “哪个 ILOSTAT 数据流包含按性别和经济活动划分的平均月收入？” （ilo_search_indicators）
• “筛选这个指标时可以使用哪些国家、年龄和性别代码？”（ilo_list_dimension_values）
• “为我提供一份越南的劳动力市场概况。”（ilo_country_labour_profile）

用自己的话提问，而不是照搬 ILO 的用词。 ILOSTAT 使用英式统计英语，而目录是按数据流名称匹配的，因此日常用语或美式用词可能导致完全没有结果。在官方目录的 1,212 个数据流中进行测量（2026-09-13），并自 0.6.0 起修复：搜索会转换术语，并告知你已进行转换。

你的搜索词	转换前结果数	ILOSTAT 的用词	结果数
labor、labor force	0	labour、labour force	176、122
wages、salary	0	earnings	107
informality	0	informal	133
gender	2	sex	1,131
productivity	0	output per worker	4
jobless	0	unemployment	108

与替代方案的比较

已经使用 ILOSTAT 的人都拥有不错的工具，而此服务不会取代其中任何一种—— 它处于工作链中的另一个环节：在提问时、在助手内部回答问题，并在答案中附上来源、数据版本和许可信息。详细信息、 并列示例和实测数据见 docs/alternatives.md。

工具	说明	适用场景
ilo-mcp-server（本项目）	托管式远程 MCP 服务，无需安装：通过 6 个工具访问约 1,200 个 ILOSTAT 数据流，每个答案都附有溯源信息块	在助手（Claude、ChatGPT、Cursor、Claude Code）中提问，且答案必须可审计
Rilostat 2.5.0（R，CRAN）	ILO 自己的 R 包，由 ILO 员工编写：支持批量下载、元数据、筛选和重塑	你使用 R，想将数据集载入数据框——反复获取整张表用于分析
sdmx1 2.27.0 / pandaSDMX 1.10.0（Python）	通用 SDMX 客户端；它们支持约 36 个数据源，ILO 是其中之一	你的数据流水线使用 Python，且需要 SDMX 对象；或者希望用同一套代码访问多个 SDMX 机构
DBnomics（API，Python 的 dbnomics，R 的 rdbnomics 0.6.4）	聚合平台，重新发布 1,071 个 ILO 数据集及其他提供方的数据，并提供统一 API	你想通过单一界面查看 ILO、IMF、OECD 和 Eurostat 的序列
ILOSTAT SDMX REST API	此服务调用的数据源本身	你正在构建自己的客户端，并希望拥有完全控制权
cyanheads/ilostat-mcp-server 0.1.2	另一个 ILOSTAT MCP 服务，可托管或本地运行：逐行标明调查值与 ILO 模型估算值，每次调用最多支持 300 个地区，并将大型结果存为可通过 SQL 查询的数据框	你需要了解每行数据是调查值还是模型估算值，或者需要查询多个国家并对大型数据集使用 SQL
Pipeworx mcp-ilostat 0.1.4	Pipeworx 网关的 ILOSTAT 工具包：使用位置式 SDMX 键，答案不含来源、许可或数值状态	你已经在使用 Pipeworx 网关，并希望将 ILOSTAT 与其中的其他数据源一同使用

以下情况请勿使用此服务：你需要的是完整数据集而非答案（Rilostat 的批量下载功能更合适）；问题涉及的不是 ILO 发布的劳动力统计数据（教育数据 → UNESCO UIS，国民账户 → IMF/World Bank）；或者你需要微观数据：ILOSTAT 发布的是汇总数据，此服务也是如此。

同系列服务采用相同设计，并提供相同的溯源信息块，覆盖其他官方数据源： IBGE（巴西统计数据）， BCB（巴西中央银行）， Senado（巴西参议院开放数据）， SIH/SUS（巴西住院数据）和 医学术语（ICD-11、ICD-10、LOINC、RxNorm、ATC、MeSH）。

使用方法（托管版 — 无需设置）

将任意 MCP 客户端指向 Streamable HTTP 端点：

https://ilo.sidneybissoli.com/mcp

支持原生远程连接的 Claude Desktop / Claude Code 及其他客户端：

{
  "mcpServers": {
    "ilostat": {
      "url": "https://ilo.sidneybissoli.com/mcp"
    }
  }
}

对于通过命令启动 MCP 服务的客户端，请使用 mcp-remote 桥接工具：

{
  "mcpServers": {
    "ilostat": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://ilo.sidneybissoli.com/mcp"]
    }
  }
}

ilo-mcp-server.sidneybissoli.workers.dev 主机名也提供服务，作为备用。

ChatGPT（Deep Research）

ChatGPT 深度研究（以及 company knowledge 和基于 Responses API 的研究工作流）只使用一个恰好暴露 search 和 fetch 的 MCP 服务——本服务在此基础上还提供 ilo_* 工具。将连接器指向托管端点，无需密钥：

https://ilo.sidneybissoli.com/mcp

search 会根据完整的 ILOSTAT 数据流目录（约 1,200 个 SDMX 数据流，涵盖就业、失业、工资、工作时间、非正规性和 SDG 劳动指标）对查询进行排序，并返回 { id, title, url }（ind:<DATAFLOW_ID>，例如 ind:DF_UNE_2EAP_SEX_AGE_RT）；fetch 会以易读的 Markdown 格式返回数据流内容，包括名称、数据版本、维度和代码列表、ILO 的默认选择，以及如何使用 ilo_get_data 查询；其中的 url 是公开的 ILOSTAT 数据浏览器页面，也是 ChatGPT 引用的链接。两者都在 structuredContent 和 _meta 中携带与其他所有工具相同的溯源信息块（文本通道遵循契约的 JSON 格式）。在 ChatGPT 开发者模式（Settings → Security and login → Developer mode）中，任何工具都可以调用；处理数据时仍应使用 ilo_* 工具。

本地运行（stdio）

不想通过第三方主机转发查询？同一服务也可以作为 本地 stdio 进程运行，直接连接官方 ILOSTAT API——工具、资源和提示词仍为 6 个，限制和溯源信息块也相同，整个过程不经过 Cloudflare。

无需安装——该软件包已发布到 npm（ilo-mcp-server，Node ≥ 20）：

{
  "mcpServers": {
    "ilostat": {
      "command": "npx",
      "args": ["-y", "ilo-mcp-server"]
    }
  }
}

也可以从源代码运行：

git clone https://github.com/SidneyBissoli/ilo-mcp-server
cd ilo-mcp-server
npm install
npm run build
node dist/cli.js   # serves MCP over stdio (Ctrl+C to stop)

（然后将客户端指向 node /path/to/ilo-mcp-server/dist/cli.js）。

与托管服务的差异都源于缺少 Cloudflare 绑定：SDMX 缓存位于进程内存中（结构和代码列表会在会话内重复使用，但不会跨会话复用）；首次搜索时会从官方端点下载搜索目录 （溯源信息中会报告真实的 retrieved_at）；没有使用指标、速率限制或身份验证。日志 输出到 stderr——stdout 仅承载 JSON-RPC 流。仓库中的 Dockerfile 会构建此 运行时（供 Glama 注册表使用）。

工具

工具	功能	来源
ilo_search_indicators	对约 1,210 个数据流进行关键词搜索（通过 offset 分页）	本地目录（不调用上游）
ilo_get_indicator_metadata	获取数据流的维度、代码列表、数据版本和默认选择	缓存的结构（未命中 → 上游）
ilo_list_dimension_values	获取一个维度的有效代码（通过 offset 分页）	缓存的代码列表（未命中 → 上游）
ilo_get_data	获取按维度和时间段筛选的观测值	每次查询调用 1 次实时 REST 接口
search	ChatGPT Deep Research 契约：根据完整数据流目录对查询进行排序，返回 { id, title, url }（ind:<DATAFLOW_ID>）	从本地目录构建的内存索引（24 h）
fetch	ChatGPT Deep Research 契约：以易读的 Markdown 格式返回单个数据流，并将公开的数据浏览器页面作为 url	缓存的结构（未命中 → 上游）

典型流程：ilo_search_indicators → ilo_get_indicator_metadata / ilo_list_dimension_values 以发现有效的筛选代码 → 使用国家和时间段筛选条件调用 ilo_get_data。

每个响应都在三个通道中携带此项目的溯源信息块 （@sbissoli/mcp-provenance，通过 provenance_mode 参数设置 concise/detailed 模式）： structuredContent、命名空间 _meta（com.sidneybissoli.ilostat/*）和文本页脚。 从 1.1.0 版本起，该信息块包含 retrieval，即调用来源诊断信息——向 ILOSTAT 发出了多少请求、进行了多少次尝试、克服了哪些异常，以及答案是否为 unstable。这些信息由项目通用的 fetch (@sbissoli/mcp-upstream) 统计；如果答案未访问 ILOSTAT（例如来自目录或缓存的结构），则为 null。

资源和提示词

三个资源（静态、text/markdown，不会调用上游），客户端可在调用工具前附加到上下文中，可省去大多数会话中花在“使用哪个数据流、哪些代码”上的 2–3 次探索调用：

URI	内容
ilostat://guide	工具工作流、稳定的代码约定（REF_AREA：ISO3 + X 汇总项、SEX、AGE、FREQ、数据流 ID 后缀）、限制、报告规则
ilostat://reference/key-dataflows	按主题列出的已验证数据流 ID（失业、就业、劳动参与率、工资、工时、非正规就业、NEET、SDG 8、生产率）
ilostat://reference/provenance	每个来源信息字段的含义，以及如何引用 ILO

三个提示词——现成的工作流，会串联工具并以引用规则收尾 （参数为字符串；期间参数可选）：

提示词	参数	结果
ilo_country_labour_profile	country、start_period、end_period	一个国家的劳动力市场概况（失业、劳动参与率、就业人口比、非正规就业、NEET、收入、工时）
ilo_compare_countries	countries、indicator、start_period、end_period	在一次数据调用中生成跨国家/汇总项的比较表，并标记模型估算值与报告数据
ilo_indicator_trend	indicator、country、start_period、end_period	一项指标的时间序列，包括首值/末值、峰值/谷值和 OBS_STATUS 断点

资源和提示词中引用的每个数据流 ID，都会由测试套件根据目录种子进行检查，因此文档不会指向搜索不到的 ID。

行为与限制

• ilo_get_data 必须提供 REF_AREA，每次调用最多 30 个区域。 ILO 网关在不受限查询时会超时（HTTP 504），因此服务端绝不会发起此类查询；对于范围较广的面板，请将区域拆分成批次和／或按期间分页（start_period/end_period）。错误消息会说明如何操作。
• 每次数据查询只进行一次实时 REST 调用。 数据永不缓存——每个 ilo_get_data 结果都在请求时从 ILOSTAT 获取。数据流结构（TTL 24 h）和代码列表（TTL 7 days，在各数据流之间共享）会缓存。
• data_vintage 是 ILO 发布的数据流最后更新日期（LAST_UPDATE 注释，已标准化为 ISO 格式）。
• retrieved_at 始终是从 ILOSTAT 提取数据的实际时间点，并与任何缓存值一同保留——绝不是构建时间或响应时间。缓存响应会注明这一点（served_from_cache: true）。
• 指标目录是本地快照（约 1,210 个数据流），会定期刷新；其自身的 retrieved_at 会在 ilo_search_indicators 的来源信息中报告，因此始终可见其时效。
• 每次上游调用都会携带可识别的 User-Agent（服务 URL + 联系方式），以便 ILO 管理员联系运营方。
• 每次上游调用都有超时和重试策略（自 1.1.0 起，依据实时 API 测量）：每次尝试 65 s——高于 ILO 网关拒绝不受限查询并返回 504 所需的约 61 s，因此合法的宽范围查询不会被此服务提前截断；遇到 5xx、429（遵循 Retry-After）和网络错误时，最多尝试 3 次，每次调用总计 70 s。超时、HTTP 504（查询范围过广）和 404（没有观测值）均不会重试。发生的情况会记录在来源信息的 retrieval 字段中。
• 语言：英语；时区：UTC（ILO 数据以英语发布）。

来源字段

• derived — 仅在确实进行了转换（聚合、服务端计算的比率、插值、协调化）时为 true，且始终附带 derivation_note；单位换算和舍入不算。此服务不会转换值，因此 derived 始终为 false（简明区块中省略）。
• notices（ilo_get_data）— 行中出现的每个不同 OBS_STATUS 值（SDMX 状态／免责声明通道，例如“序列中断”）、UNIT_MEASURE 和 UNIT_MULT（例如“Thousands”：单位和比例属于数值的一部分），并注明带有该值的观测数量。文本页脚中会重复这些信息；没有需要说明的内容时则省略。技术性逐观测属性（DECIMALS 等）保留在行中（rows[].attributes）。
• revision（自契约 1.3、服务端 1.6.4 起）— 始终为 current：ILOSTAT 仅提供当前版本，之后可能会修订；对于数据响应，说明会注明 ILO 在每次发布时都会重新估算模型序列（_2 ID），包括往年数据。

表面指纹，可从注册表核验

每个版本都会在其 MCP Registry 条目中发布此版本所提供表面（initialize、工具、资源、提示词）的 sha256，以及无需凭证即可响应的 methods。表面发生变化却未提升版本号会导致构建失败；注册表中的指纹可让客户端在本地核验同样的信息。规范形式和流程：@sbissoli/mcp-surface 的 SPEC.md。 自行核验（Node 18+，无依赖项）：

curl -sO https://raw.githubusercontent.com/SidneyBissoli/mcp-br-commons/main/packages/mcp-surface/exemplos/verify.mjs
node verify.mjs io.github.SidneyBissoli/ilo-mcp-server

数据许可和署名

• ILOSTAT 数据和元数据：CC BY 4.0（自 2023-05-03 起；许可证核验于 2026-08-04）。
• 每个响应中的 ILO 署名（citation 字段）： International Labour Organization, ILOSTAT, https://ilostat.ilo.org/data/, accessed <date>.
• 不使用 ILO 徽标。本服务未获 ILO 背书。

自托管／开发

以下内容仅在运行自己的实例时需要；使用公共服务无需这些步骤。

npm install
npm run typecheck && npm test   # offline suite (parsers, key, tools, output contract, resources/prompts, in-memory catalogue, vocabulary, eval fixtures)
npm run dev                     # http://localhost:8787/mcp (Worker)
npm run build && npm start      # stdio runtime (dist/cli.js)

# Catalogue seed (D1) — required before first use:
node scripts/seed-catalog.mjs   # downloads via curl and generates scripts/seed-catalog.sql
npx wrangler d1 execute ilostat-catalog --local  --file=scripts/seed-catalog.sql
npx wrangler d1 execute ilostat-catalog --remote --file=scripts/seed-catalog.sql

npm run deploy
node scripts/smoke-mcp.mjs      # smoke test against production (initialize → 6 tools → search → fetch → errors)
npm run manifest:lhm            # regenerate tools/resources/prompts in lhm.plugin.json from the real server
# (the seed also writes tests/fixtures/catalog-ids.txt — the versioned id list the tests check resources/prompts against)

绑定（参见 wrangler.jsonc）：KV SDMX_CACHE、D1 CATALOG_DB、Durable Object USAGE（基于 SQLite 的使用计数器）、CF_VERSION_METADATA。可选的 Bearer 身份验证（wrangler secret put API_KEY）；按 IP 进行令牌桶速率限制。

运维说明：

• ILOSTAT 仅在通过 Accept 标头协商时返回 JSON（application/vnd.sdmx.{structure,data}+json）；?format= 会被忽略，并返回 XML。
• ILO 网关会对 Node 的 fetch（undici）默认发送的 Accept-Language: * 标头返回 HTTP 500（languageTag1）；因此，每次上游调用都会显式设置 Accept-Language: en（Cloudflare 的运行时不会发送此类标头，因此 Worker 从未受到影响）。网关还要求提供可识别的 User-Agent。
• 目录刷新需手动进行（无 cron）：每季度一次；如果上游存在的数据流未出现在搜索结果中，则立即刷新。流程：执行上面的三个种子命令。数据查询始终为实时查询，因此只有搜索目录可能会过时，而且其时效性会在来源信息中公开。

评测

@sbissoli/mcp-evals：evals/fixtures/queries.ts 中有 24 个测试样例，可通过 npm test 离线验证。使用真实模型运行（npm run eval）会调用 Anthropic API，且需要 ANTHROPIC_API_KEY（未设置时会退出并显示说明）。2026-08-07 的运行结果：top-1 100%（24/24） — evals/results/。

端到端：evals/e2e/evaluation.xml 中有 10 个答案唯一且可核验的复杂问题；答案已根据生产环境手动验证（evals/e2e/validacao-respostas.md）。2026-08-07 的运行结果（Sonnet）：精确字符串匹配 9/10；实质正确 10/10 — evals/results/2026-08-07-e2e.md。

端点

路由	用途
/	着陆页（服务身份与联系方式 — 公开）
/health	存活状态
/status	版本、工具／资源／提示词数量与名称、来源契约版本、当前部署（为 README 徽章提供数据）
/metrics	汇总使用情况（仅 MCP 端点；不包含 IP 或查询内容）
/.well-known/mcp/server-card.json	供目录扫描器使用的 MCP 服务卡片（serverInfo、工具、资源、提示词 — 根据运行中的服务生成）
/mcp	MCP Streamable HTTP

安全

Snyk Agent Scan（2026-08-07）：已通过 — 报告见 security/。

许可证

代码：MIT。数据：ILOSTAT，CC BY 4.0（见上文“数据许可证与署名”）。

隐私

托管服务的隐私政策：PRIVACY.md。

联系方式

Sidney da Silva Pereira Bissoli — [email protected]。本服务未获 ILO 背书。