loading…
Search for a command to run...
loading…
Provides access to over 5,000 macroeconomic indicators from the Banco Central de Reserva del Perú (BCRP) statistical database. It enables AI agents to search fo
Provides access to over 5,000 macroeconomic indicators from the Banco Central de Reserva del Perú (BCRP) statistical database. It enables AI agents to search for indicators, fetch time-series data, and generate professional economic charts.
MCP Server and Python library for the Banco Central de Reserva del Perú (BCRP) Statistical API. Access over 5,000 macroeconomic indicators directly from your AI agent or Python environment.
The mcp-bcrp package provides a standardized interface to the BCRP statistical database through the Model Context Protocol (MCP). It supports both direct Python usage and integration with AI assistants such as Claude, Gemini, and other MCP-compatible agents.
The library implements:
| Feature | Description |
|---|---|
| Smart Search | Deterministic search engine with fuzzy matching, attribute extraction, and ambiguity detection |
| Async Native | Built on httpx for non-blocking HTTP requests with connection pooling |
| Dual Interface | Use as MCP server for AI agents or as standalone Python library |
| Chart Generation | Generate publication-ready charts with automatic Spanish date parsing |
| Full Coverage | Access to 5,000+ BCRP economic indicators across all categories |
| Metadata Cache | Local caching of 17MB metadata file for fast offline searches |
httpx, pandas, fastmcp, rapidfuzz, matplotlibpip install mcp-bcrp
git clone https://github.com/YOUR_USERNAME/mcp-bcrp.git
cd mcp-bcrp
pip install -e .
pip install "mcp-bcrp[charts]" # Include matplotlib for chart generation
pip install "mcp-bcrp[dev]" # Include development dependencies
Add the following to your MCP configuration file (e.g., mcp_config.json):
{
"mcpServers": {
"bcrp-api": {
"command": "python",
"args": ["C:/absolute/path/to/mcp_bcrp/run.py"]
}
}
}
[!TIP] If you have installed the package via pip, you can also use
["-m", "mcp_bcrp"]as the arguments.
| Variable | Description | Default |
|---|---|---|
BCRP_CACHE_DIR |
Directory for metadata cache | User cache dir |
BCRP_TIMEOUT |
HTTP request timeout in seconds | 120 |
Once configured, the server can be invoked by MCP-compatible AI assistants:
User: What is the current policy interest rate in Peru?
Agent: [calls search_series("tasa politica monetaria")]
Agent: [calls get_data(["PD04722MM"], "2024-01/2025-01")]
import asyncio
from mcp_bcrp.client import AsyncBCRPClient, BCRPMetadata
async def main():
# Initialize metadata client
metadata = BCRPMetadata()
await metadata.load()
# Search for an indicator (deterministic)
result = metadata.solve("tasa politica monetaria")
print(result)
# Output: {'codigo_serie': 'PD04722MM', 'confidence': 1.0, ...}
# Fetch time series data
client = AsyncBCRPClient()
df = await client.get_series(
series_codes=["PD04722MM"],
start_date="2024-01",
end_date="2025-01"
)
print(df.head())
asyncio.run(main())
| Tool | Parameters | Description |
|---|---|---|
search_series |
query: str |
Search BCRP indicators by keyword. Returns deterministic match or ambiguity error. |
get_data |
series_codes: list[str], period: str |
Fetch raw time series data. Period format: YYYY-MM/YYYY-MM. |
get_table |
series_codes: list[str], names: list[str], period: str |
Get formatted table with optional custom column names. |
plot_chart |
series_codes: list[str], period: str, title: str, names: list[str], output_path: str |
Generate professional PNG chart with automatic date parsing. |
| Resource | URI | Description |
|---|---|---|
| Metadata | bcrp://metadata |
Summary of cached metadata and stats. |
| Key Indicators | bcrp://indicators/key |
List of most common economic indicators. |
| Help | bcrp://help |
Usage guide and tips. |
| Prompt | Description |
|---|---|
economista_peruano |
System prompt to analyze data as a BCRP Senior Economist with rigorous methodology. |
analista_financiero |
Expert persona for short-term financial market analysis (Forex, Rates). |
explorador_datos |
Assistant to help find the correct series codes for a given topic. |
The following are commonly used indicator codes:
| Category | Code | Description | Frequency |
|---|---|---|---|
| Monetary Policy | PD04722MM |
Reference Interest Rate | Monthly |
| Exchange Rate | PD04638PD |
Interbank Exchange Rate (Sell) | Daily |
| Inflation | PN01270PM |
CPI Lima Metropolitan | Monthly |
| Copper Price | PN01652XM |
International Copper Price (c/lb) | Monthly |
| GDP Growth | PN01713AM |
Agricultural GDP (Var. %) | Annual |
| Business Expectations | PD38048AM |
GDP Expectations 12 months | Monthly |
| International Reserves | PN00015MM |
Net International Reserves | Monthly |
[!NOTE] Series codes follow the BCRP naming convention. Use
search_seriesto find the appropriate code for your query.
The search engine implements a deterministic pipeline designed for high precision:
Query Input
│
▼
┌─────────────────────────────┐
│ 1. Canonicalization │ Lowercase, remove accents, filter stopwords
└─────────────────────────────┘
│
▼
┌─────────────────────────────┐
│ 2. Attribute Extraction │ Currency (USD/PEN), horizon, component type
└─────────────────────────────┘
│
▼
┌─────────────────────────────┐
│ 3. Hard Filters │ Eliminate series not matching attributes
└─────────────────────────────┘
│
▼
┌─────────────────────────────┐
│ 4. Fuzzy Scoring │ Token sort ratio using RapidFuzz
└─────────────────────────────┘
│
▼
┌─────────────────────────────┐
│ 5. Ambiguity Detection │ Return error if top matches are too close
└─────────────────────────────┘
│
▼
Deterministic Result or Explicit Ambiguity Error
mcp_bcrp/
├── __init__.py # Package initialization and version
├── server.py # FastMCP server with tool definitions
├── client.py # AsyncBCRPClient and BCRPMetadata classes
└── search_engine.py # Deterministic search pipeline implementation
run.py # MCP server entry point
bcrp_metadata.json # Cached metadata (17MB, auto-downloaded)
[!WARNING] API Rate Limits: The BCRP API does not publish official rate limits. Implement appropriate delays between requests in production applications to avoid IP blocking.
[!WARNING] Data Freshness: Metadata cache (
bcrp_metadata.json) may become stale. Delete the file periodically to force a refresh of available indicators.
[!CAUTION] Unofficial Package: This is an independent implementation and is not officially endorsed by the Banco Central de Reserva del Peru. Data accuracy depends on the upstream API.
Date Format: The BCRP API returns dates in Spanish format (e.g., "Ene.2024"). The library handles this automatically, but custom date parsing may be required for edge cases.
Series Availability: Not all series are available for all time periods. The API returns empty responses for unavailable date ranges.
Metadata Size: The complete metadata file is approximately 17MB. Initial load may take several seconds on slow connections.
Frequency Detection: The library attempts to auto-detect series frequency, but some series may require explicit specification.
Contributions are welcome. Please follow these guidelines:
git checkout -b feature/improvement)pytest)See CONTRIBUTING.md for detailed guidelines.
This project is licensed under the MIT License. See LICENSE for the full text.
| Project | Description |
|---|---|
| wbgapi360 | Enterprise-grade MCP Client for World Bank Data API. Provides access to World Development Indicators, global rankings, country comparisons, and professional FT-style visualizations. |
Both libraries can be used together to build comprehensive macroeconomic analysis pipelines combining Peru-specific BCRP data with global World Bank indicators.
Disclaimer: This software is provided "as is" without warranty of any kind. The authors are not responsible for any errors in the data or any decisions made based on the information provided by this library.
Добавь это в claude_desktop_config.json и перезапусти Claude Desktop.
{
"mcpServers": {
"mcp-bcrp": {
"command": "npx",
"args": []
}
}
}