mcp-nbb

벨기에 국립은행(National Bank of Belgium) SDMX 통계 API용 MCP 서버입니다.

221개의 NBB 데이터플로우(194 BE2 + 27 IMF/SDDS)를 6개의 LLM 친화적 도구와 3개의 탐색 가능한 리소스로 노출하며, 번들로 제공되는 강화된 카탈로그를 통해 LLM이 중복 API 호출 없이 데이터플로우를 발견, 설명, 쿼리할 수 있습니다.

• 업스트림: https://nsidisseminate-stat.nbb.be/rest (NSI Web Service v8)

• 전송: stdio (표준 MCP)

• Python: 3.11+

• 플랫폼: Linux, macOS, Windows

• 221개 데이터플로우가 14개 카테고리로 분류됨 — DATAFLOWS_CATALOG.md 참조

설치

PyPI에서 설치 (권장)

# With uv (runs without installing globally)
uvx mcp-nbb

# Or install into a regular venv
pip install mcp-nbb

소스에서 설치

git clone https://github.com/lacausecrypto/mcp-nbb.git
cd mcp-nbb
pip install -e .

패키지에는 전체 강화 카탈로그(~9 MB, src/nbb_mcp/data/catalog/ 아래)가 포함되어 있습니다. 일반적인 사용에는 빌드 단계가 필요하지 않습니다.

Related MCP server: OECD MCP Server

Claude Desktop 구성

macOS에서는 ~/Library/Application Support/Claude/claude_desktop_config.json을, Windows에서는 %APPDATA%\Claude\claude_desktop_config.json을, Linux에서는 해당 파일을 편집하세요.

uvx 사용 (PyPI에 게시되면 권장)

{
  "mcpServers": {
    "nbb": {
      "command": "uvx",
      "args": ["mcp-nbb"]
    }
  }
}

로컬 편집 가능 설치에서

macOS / Linux:

{
  "mcpServers": {
    "nbb": {
      "command": "/Users/you/projects/mcp-nbb/.venv/bin/mcp-nbb"
    }
  }
}

Windows:

{
  "mcpServers": {
    "nbb": {
      "command": "C:\\Users\\you\\projects\\mcp-nbb\\.venv\\Scripts\\mcp-nbb.exe"
    }
  }
}

Claude Desktop을 다시 시작하면 MCP 패널에 6개의 nbb_* 도구가 나타납니다.

도구

nbb_quick 주제

리소스

Claude에서의 예시 프롬프트

"지난 달 EUR/USD 환율은 얼마인가요?" → nbb_quick("exchange_rate", currency="USD", frequency="D", last_n_observations=30)

"2020년 이후 벨기에 GDP 성장률과 실업률을 비교해 주세요." → nbb_compare([{dataflow_id:"DF_QNA_DISS",label:"GDP"}, {dataflow_id:"DF_UNEMPLOY_RATE",label:"Unemployment"}], start_period="2020-Q1")

"소비자 신용에 관한 NBB 데이터플로우를 찾아주세요." → nbb_search("consumer credit") → nbb_describe(...) → nbb_query(...).

구성 (환경 변수)

모든 설정에는 합리적인 기본값이 있으며 환경 변수로 재정의할 수 있습니다.

기본 캐시 경로는 다음과 같이 결정됩니다:

• Linux: ~/.cache/mcp-nbb/

• macOS: ~/Library/Caches/mcp-nbb/

• Windows: %LOCALAPPDATA%\mcp-nbb\Cache\

카탈로그 새로고침

번들로 제공되는 src/nbb_mcp/data/catalog/ 스냅샷은 221개 데이터플로우 각각에 대해 DSD + 코드리스트를 가져와 재생성됩니다:

mcp-nbb-build-catalog --force

옵션:

• --force — 기존 피시를 무시하고 모든 피시를 다시 빌드합니다.

• --limit N — 처음 N개 흐름만 처리합니다 (디버그).

• --only BE2/DF_EXR,BE2/DF_HICP_2025 — 특정 흐름만 다시 빌드합니다.

• --concurrency 5 — 병렬 DSD 요청.

전체 재빌드는 라이브 API에 대해 약 80초가 걸립니다. 카탈로그 크기는 차원당 200개 코드로 코드리스트를 잘라내어 약 9MB로 제한됩니다 (일부 IMF 흐름에는 65,000개 이상의 코드가 있습니다).

주간 GitHub Action(build-catalog.yml)이 카탈로그를 재빌드하고 변경 사항이 감지되면 PR을 엽니다.

문제 해결

"WAF가 HTML 리디렉션을 반환했습니다"

NBB API는 브라우저와 유사한 User-Agent와 Origin: https://dataexplorer.nbb.be 헤더가 없는 모든 요청에 대해 HTML 200 리디렉션을 반환하는 WAF 뒤에 있습니다. 클라이언트는 기본적으로 둘 다 주입합니다. NBB_USER_AGENT를 재정의하는 경우 실제처럼 보이는 브라우저 문자열을 유지하세요.

데이터 쿼리에서 "HTTP 404 NoResultsFound"

SDMX 키가 어떤 시리즈와도 일치하지 않았습니다. nbb_describe(dataflow_id)를 사용하여 유효한 코드를 확인하거나, filters={} / key="all"을 전달하여 모든 것을 검색한 다음 start_period/end_period로 좁히세요.

"관측치가 너무 많아 잘렸습니다"

모든 데이터 응답은 기본적으로 max_observations=200으로 제한됩니다. nbb_query(max_observations=1000)로 늘리거나 기간 창으로 쿼리를 좁히세요.

카탈로그를 찾을 수 없음

번들로 제공되는 src/nbb_mcp/data/catalog/ 없이 실행하는 경우 mcp-nbb-build-catalog를 한 번 실행하여 채우세요.

개발

전체 개발 워크플로는 CONTRIBUTING.md를 참조하세요. 간단히:

pip install -e ".[dev]"
pytest                     # full suite (unit + integration + E2E)
pytest -m "not e2e"        # fast subset
ruff check src tests
mcp-nbb-build-catalog      # refresh the bundled catalogue
mcp-nbb                    # run the server (stdio)

CI는 Python 3.11 및 3.12로 Linux, macOS, Windows에서 실행됩니다. 분류된 인벤토리는 DATAFLOWS_CATALOG.md를 참조하세요.

보안

취약점은 비공개로 보고해 주세요 — SECURITY.md를 참조하세요.

라이선스

MIT — 전체 텍스트는 LICENSE를 참조하세요.

고지 사항

이 프로젝트는 벨기에 국립은행과 제휴하거나 보증하지 않습니다. 이는 공개 SDMX REST API의 독립적인 클라이언트입니다. 브라우저와 유사한 User-Agent 및 Origin 헤더는 업스트림 WAF에서 요구하며 공개 통계 데이터에 접근하는 데만 사용됩니다. 사용자는 NBB의 이용 약관을 준수할 책임이 있습니다.