mcp-nbb

Servidor MCP para la API estadística SDMX del National Bank of Belgium.

Expone los 221 flujos de datos NBB (194 BE2 + 27 IMF/SDDS) como 6 herramientas amigables para LLM y 3 recursos navegables, con un catálogo enriquecido incluido para que el LLM pueda descubrir, describir y consultar flujos de datos sin llamadas API redundantes.

• Fuente: https://nsidisseminate-stat.nbb.be/rest (NSI Web Service v8)

• Transporte: stdio (MCP estándar)

• Python: 3.11+

• Plataformas: Linux, macOS, Windows

• 221 flujos de datos clasificados en 14 categorías — ver DATAFLOWS_CATALOG.md

Instalación

Desde PyPI (recomendado)

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

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

Desde el código fuente

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

El paquete incluye el catálogo enriquecido completo (~9 MB en src/nbb_mcp/data/catalog/). No se requiere ningún paso de compilación para el uso normal.

Related MCP server: OECD MCP Server

Configuración de Claude Desktop

Edite ~/Library/Application Support/Claude/claude_desktop_config.json en macOS, %APPDATA%\Claude\claude_desktop_config.json en Windows, o el equivalente en Linux.

Usando uvx (recomendado una vez publicado en PyPI)

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

Desde una instalación editable local

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"
    }
  }
}

Reinicie Claude Desktop — las 6 herramientas nbb_* aparecen en el panel MCP.

Herramientas

Temas de nbb_quick

Recursos

Ejemplos de prompts en Claude

"¿Cuál es el tipo de cambio EUR/USD del último mes?" → nbb_quick("exchange_rate", currency="USD", frequency="D", last_n_observations=30)

"Compare el crecimiento del PIB belga con la tasa de desempleo desde 2020." → nbb_compare([{dataflow_id:"DF_QNA_DISS",label:"GDP"}, {dataflow_id:"DF_UNEMPLOY_RATE",label:"Unemployment"}], start_period="2020-Q1")

"Encuentre flujos de datos NBB sobre crédito al consumo." → nbb_search("consumer credit") → nbb_describe(...) → nbb_query(...).

Configuración (variables de entorno)

Todos los ajustes tienen valores predeterminados razonables; se pueden anular mediante variables de entorno.

La ruta de caché predeterminada se resuelve a:

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

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

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

Actualización del catálogo

La instantánea incluida en src/nbb_mcp/data/catalog/ se regenera obteniendo el DSD + listas de códigos para cada uno de los 221 flujos de datos:

mcp-nbb-build-catalog --force

Opciones:

• --force — reconstruir cada ficha, ignorando las existentes.

• --limit N — procesar solo los primeros N flujos (depuración).

• --only BE2/DF_EXR,BE2/DF_HICP_2025 — reconstruir flujos específicos.

• --concurrency 5 — solicitudes DSD en paralelo.

Una reconstrucción completa tarda ~80 segundos contra la API en vivo. El tamaño del catálogo está limitado a ~9 MB truncando las listas de códigos a 200 códigos por dimensión (algunos flujos del FMI tienen más de 65 000 códigos).

Una GitHub Action semanal (build-catalog.yml) reconstruye el catálogo y abre un PR si se detecta desviación.

Solución de problemas

"El WAF devolvió una redirección HTML"

La API de NBB está detrás de un WAF que devuelve una redirección HTML 200 para cualquier solicitud sin un User-Agent similar a un navegador y un encabezado Origin: https://dataexplorer.nbb.be. El cliente inyecta ambos por defecto. Si anula NBB_USER_AGENT, mantenga una cadena de navegador con apariencia genuina.

"HTTP 404 NoResultsFound" en una consulta de datos

La clave SDMX no coincidió con ninguna serie. Use nbb_describe(dataflow_id) para ver códigos válidos, o pase filters={} / key="all" para recuperar todo y luego acote mediante start_period/end_period.

"Demasiadas observaciones, truncado"

Cada respuesta de datos está limitada a max_observations=200 por defecto. Auméntela mediante nbb_query(max_observations=1000) o acote la consulta con una ventana de período.

Catálogo no encontrado

Si ejecuta sin el src/nbb_mcp/data/catalog/ incluido, ejecute mcp-nbb-build-catalog una vez para poblarlo.

Desarrollo

Consulte CONTRIBUTING.md para el flujo de trabajo de desarrollo completo. Forma corta:

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 se ejecuta en Linux, macOS y Windows con Python 3.11 y 3.12. Consulte DATAFLOWS_CATALOG.md para el inventario clasificado.

Seguridad

Por favor, reporte vulnerabilidades de forma privada — consulte SECURITY.md.

Licencia

MIT — consulte LICENSE para el texto completo.

Aviso legal

Este proyecto no está afiliado ni respaldado por el National Bank of Belgium. Es un cliente independiente de su API REST SDMX pública. Los encabezados User-Agent y Origin similares a un navegador son requeridos por el WAF ascendente y se utilizan únicamente para acceder a datos estadísticos públicos. Los usuarios son responsables de cumplir con los términos de uso de NBB.