cnbs-mcp-server

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

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:

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.