MCP 服务器

cnbs-mcp-server

Enables querying statistical data from China NBS, World Bank, IMF, OECD, BIS, census, and department statistics via MCP tools.

README

<h1 align="center">cnbs-mcp-server</h1>

<p align="center"> A read-only MCP server that lets AI agents query official China NBS and international statistics without hand-stitching scattered public APIs. </p>

Why this exists

Official statistics are easy to trust but hard for agents to use correctly. The newer NBS API uses UUID-based catalog and indicator IDs, the same business indicator may be split across time slices, and useful fields such as unit, region, period, and statistical notes are spread across multiple calls.

cnbs-mcp-server turns that friction into agent-friendly tools. It gives LLMs a guided path for search, latest values, historical series, regional comparison, macro snapshots, and international cross-checks across World Bank, IMF, OECD, BIS, census, and department statistics.

Capabilities

Need	Tool family	What it helps with
Search China NBS indicators	`cnbs_search`, `cnbs_batch_search`	Find official indicators and latest values by keyword.
Fetch historical series	`cnbs_fetch_series`, `cnbs_quick_query`	Resolve dataset and indicator IDs, then fetch time series.
Compare regions or periods	`cnbs_compare`	Compare a metric across provinces, cities, or years.
Get a macro snapshot	`cnbs_economic_snapshot`	Pull GDP, CPI, PPI, PMI, unemployment, industry, trade, money supply, and more in one call.
Query international sources	`ext_world_bank`, `ext_imf`, `ext_oecd`, `ext_bis`	Access global macro, finance, trade, employment, and forecast data.
Check China census and departments	`ext_cn_census`, `ext_cn_department*`	Query census, fiscal, industry, agriculture, monetary, energy, housing, and other department statistics.
Cross-check sources	`ext_global_compare`	Compare World Bank and IMF values for the same country/indicator idea.

Quick start

npm ci
npm run build
node dist/index.js --host 127.0.0.1 --port 12345

The stateless Streamable HTTP endpoint accepts POST / and POST /mcp. Set CNBS_MCP_SERVER_AUTH_TOKEN or pass --auth-token to require a Bearer token. Request bodies are limited to 1 MB.

MCP client configuration

Start the server first, then add it to any MCP client that supports Streamable HTTP:

{
  "mcpServers": {
    "cnbs": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:12345/mcp"
    }
  }
}

If you enabled Bearer authentication, include the same token in the client configuration:

{
  "mcpServers": {
    "cnbs": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:12345/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

Docker

Published Docker images are available from GitHub Container Registry for linux/amd64 and linux/arm64.

docker pull ghcr.io/eliseowzy/cnbs-mcp-server:1.1.0-beta.2

Run the published image:

docker run --rm \
  -p 12345:12345 \
  -e CNBS_MCP_SERVER_AUTH_TOKEN=your-token \
  -e LOG_LEVEL=info \
  -v "$PWD/logs:/app/logs" \
  ghcr.io/eliseowzy/cnbs-mcp-server:1.1.0-beta.2

The MCP endpoint is:

http://127.0.0.1:12345/mcp

To build and run from source with Docker Compose:

docker compose up --build

To use the published image with Compose, override the service image:

services:
  cnbs-mcp-server:
    image: ghcr.io/eliseowzy/cnbs-mcp-server:1.1.0-beta.2
    ports:
      - "12345:12345"
    restart: unless-stopped
    environment:
      CNBS_MCP_SERVER_AUTH_TOKEN: "${CNBS_MCP_SERVER_AUTH_TOKEN:-}"
      LOG_LEVEL: "${LOG_LEVEL:-info}"
      LOG_DIR: /app/logs
    volumes:
      - ./logs:/app/logs

Logs are emitted as structured JSON to stdout and daily rotating files under ./logs. Configure LOG_LEVEL and LOG_DIR as needed.

Design notes

This repository is also a map of how to build data tools for LLM agents:

If you want to understand...	Read
How the service guides agents, normalizes noisy inputs, returns stable structured output, and handles semantic errors	`docs/plans/agent-friendly-design.md`
How quick query compresses the NBS flow from search to indicator resolution to series fetch	`docs/plans/quick-query-design.md`
How caching uses LRU, TTL, in-flight request deduplication, stale-while-revalidate, and a cache hub	`docs/plans/cache-module-design.md`
How cache keys avoid collisions between metric, period, area, and external-source parameters	`docs/plans/cache-key-design.md`

Reading path: start with Quick start if you only want to run it; read the agent-friendly design if you want the core product thinking; read the cache docs if you are maintaining performance and upstream reliability.

Development

npm run lint
npm test
npm run build

Use the cnbs_get_guide tool for the complete tool catalog and query workflows. The same guide content is maintained in llms.txt for LLM-oriented usage.