Metadata-Version: 2.5
Name: bcrp-mcp
Version: 0.1.0
Summary: MCP server for the Banco Central de Reserva del Peru (BCRP) statistics API — access macroeconomic data, exchange rates, interest rates, monetary indicators, and more
Project-URL: Homepage, https://github.com/JOSETRA44/bcrp-mcp
Project-URL: Repository, https://github.com/JOSETRA44/bcrp-mcp
Project-URL: Bug Tracker, https://github.com/JOSETRA44/bcrp-mcp/issues
Project-URL: Documentation, https://estadisticas.bcrp.gob.pe/estadisticas/series/ayuda/api
Author-email: JOSETRA44 <drivearchiver@gmail.com>
License: MIT License
        
        Copyright (c) 2026 JOSETRA44
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: ai,banco-central,bcrp,economic-data,exchange-rate,gdp,inflation,llm,macroeconomics,mcp,model-context-protocol,peru,statistics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Requires-Dist: anyio>=4.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp<2.0.0,>=1.0.0
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Description-Content-Type: text/markdown

<img width="1600" height="500" alt="BCRP MCP" src="https://github.com/user-attachments/assets/79323612-ebec-49ea-91d5-321b5950bbbc" />

[![PyPI](https://img.shields.io/pypi/v/bcrp-mcp?logo=pypi&logoColor=white)](https://pypi.org/project/bcrp-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/bcrp-mcp?logo=python&logoColor=white)](https://pypi.org/project/bcrp-mcp/)
[![Publish](https://github.com/JOSETRA44/BCRP-mcp/actions/workflows/publish.yml/badge.svg)](https://github.com/JOSETRA44/BCRP-mcp/actions/workflows/publish.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

# BCRP MCP

<!-- mcp-name: io.github.JOSETRA44/bcrp-mcp -->

Servidor [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) para
consultar **BCRPData**, la base oficial de estadísticas económicas del
[Banco Central de Reserva del Perú (BCRP)](https://www.bcrp.gob.pe/).

Permite a clientes MCP y agentes de IA consultar tipos de cambio, tasas de
interés, reservas internacionales, liquidez, crédito, commodities, bolsa y PBI.
La API del BCRP es pública: **no se necesita API key ni registro**.

## Instalación rápida

Se requiere Python 3.11 o posterior.

### Con `uvx` (recomendado para clientes MCP)

```bash
uvx bcrp-mcp
```

### Con `pip`

```bash
python -m pip install bcrp-mcp
bcrp-mcp
```

La instalación también proporciona el CLI `bcrp`:

```bash
bcrp --help
bcrp catalog search "tipo de cambio"
bcrp series latest PD04637PD --n 5
```

### Desde el código fuente

```bash
git clone https://github.com/JOSETRA44/BCRP-mcp.git
cd BCRP-mcp
uv sync
uv run bcrp-mcp
```

## Configuración en clientes MCP

El servidor usa transporte stdio. Con `uvx`, la configuración es la misma en
Claude Desktop, Claude Code, Cursor y otros clientes compatibles:

```json
{
  "mcpServers": {
    "bcrp": {
      "command": "uvx",
      "args": ["bcrp-mcp"]
    }
  }
}
```

En VS Code + GitHub Copilot (`.vscode/mcp.json`):

```json
{
  "servers": {
    "bcrp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["bcrp-mcp"]
    }
  }
}
```

## Herramientas MCP

| Herramienta | Uso |
|---|---|
| `bcrp_get_series` | Obtiene 1–10 series con un rango opcional; deben compartir frecuencia. |
| `bcrp_get_latest` | Obtiene los últimos valores de 1–10 series. |
| `bcrp_get_series_long` | Exporta hasta 50 series en una tabla larga, incluso con frecuencias mixtas. |
| `bcrp_describe_series` | Consulta nombre, frecuencia y rango disponible de una serie. |
| `bcrp_search_catalog` | Busca códigos en el catálogo curado de indicadores. |
| `bcrp_list_catalog_categories` | Lista las categorías disponibles. |
| `bcrp_get_macro_snapshot` | Devuelve un resumen de indicadores macroeconómicos clave. |

Ejemplos de preguntas:

```text
¿Cuál es el tipo de cambio actual en Perú?
Compara la tasa de referencia y las reservas internacionales desde 2020.
Obtén un snapshot de los principales indicadores de la economía peruana.
```

## CLI

El comando `bcrp` usa la misma lógica que el servidor MCP y admite salida para
terminal o automatización:

```bash
bcrp series describe PD04637PD
bcrp series latest PD04637PD PD12301MD --n 5
bcrp series get PN00196MM --start 2020-1 --end 2024-12
bcrp catalog categories
bcrp macro snapshot
```

Opciones útiles:

```bash
bcrp series latest PD04637PD --n 5 --json
bcrp series latest PD04637PD --n 5 --ascii --no-color
```

Los formatos de período dependen de la frecuencia: diario
`DD-MM-YYYY`, mensual `YYYY-M`, trimestral `YYYY-Q` y anual `YYYY`.
Las series de una misma consulta deben tener la misma frecuencia, salvo
`bcrp_get_series_long`.

## Configuración opcional

Todos los valores tienen valores predeterminados razonables y pueden definirse
con variables de entorno o un archivo `.env`:

| Variable | Predeterminado | Descripción |
|---|---:|---|
| `BCRP_CACHE_TTL` | `300` | Duración de la caché en segundos; `0` la desactiva. |
| `BCRP_TIMEOUT` | `30` | Timeout HTTP en segundos. |
| `BCRP_MAX_RETRIES` | `3` | Reintentos ante errores transitorios. |
| `BCRP_LANGUAGE` | `esp` | Idioma de nombres: `esp` o `ing`. |
| `LOG_LEVEL` | `INFO` | Nivel de logging. |

No se configura ninguna credencial: BCRPData es de acceso abierto.

## Desarrollo

```bash
uv sync
uv run pytest -q
uv run python -m build
```

El proyecto usa `src/` layout, Hatchling para construir el paquete y publica
dos entry points: `bcrp-mcp` (servidor) y `bcrp` (CLI).

## Publicación

Las versiones se publican mediante GitHub Actions al crear un release de
GitHub. El workflow `.github/workflows/publish.yml` ejecuta las pruebas,
construye los artefactos y publica en PyPI usando Trusted Publishing (OIDC);
no requiere un token de PyPI almacenado en secretos.

## Datos y licencia

Los datos provienen de [BCRPData](https://estadisticas.bcrp.gob.pe/estadisticas/series/).
Consulte sus [condiciones de uso](https://estadisticas.bcrp.gob.pe/estadisticas/series/ayuda/condicionesUso).

MIT — consulte [LICENSE](LICENSE).

## Documentación del proyecto

- [CHANGELOG.md](CHANGELOG.md): historial de cambios.
- [CONTRIBUTING.md](CONTRIBUTING.md): guía para contribuir.
- [SECURITY.md](SECURITY.md): reporte de vulnerabilidades.
- [server.json](server.json): metadatos para el registro MCP.
