bcb-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| BCB_MCP_TIMEOUT | No | HTTP timeout (seconds). | 60 |
| BCB_MCP_MAX_ROWS | No | Default observations kept per series. | 5000 |
| BCB_MCP_CACHE_DIR | No | Cache directory. | ~/.cache/bcb-mcp |
| BCB_MCP_MAX_RETRIES | No | Retries per request (exponential backoff). | 3 |
| BCB_MCP_MIN_INTERVAL | No | Minimum seconds between requests. | 0.2 |
| BCB_MCP_MAX_CONCURRENCY | No | Concurrent series downloads. | 4 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Brazilian macro and financial time series from the Central Bank of Brazil (BCB-SGS). Start with search_series() to translate a concept into an SGS id (the bundled dictionary understands Portuguese and English, and can also query the live BCB catalog). Then call get_series() for the observations or get_series_stats() for a compact summary. Long histories are fetched in chunks, cached as parquet files and served from disk on later calls; query_cache() runs read-only DuckDB SQL over everything cached. Units matter: rates are percentages, credit and fiscal series are usually R$ million, external sector series are US$ million. Always report the unit and the last observation date.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| logging | {} |
| prompts | {
"listChanged": true
} |
| resources | {
"subscribe": false,
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| search_seriesA | Find BCB-SGS series ids from natural language. Searches the bundled curated dictionary (151 key Brazilian macro series, with Portuguese and English aliases) and, optionally, the official BCB catalog. Always call this before get_series() when you do not know the id. |
| list_categoriesA | List the dictionary categories with descriptions and example series ids. |
| list_seriesC | Browse the curated dictionary, optionally restricted to one category. |
| describe_seriesA | Show dictionary metadata (name, unit, frequency, source, description) and cache state. |
| get_seriesA | Download BCB-SGS time series (the analogue of GetBCBData::gbcbd_get_series). Long spans are split into API-friendly chunks automatically, results are
cached as parquet files, and only missing date ranges are downloaded on
subsequent calls. Failed ids are reported in Rows are compact: each one has ref_date, value and series_id. The name,
unit, frequency and source of every series are in the |
| get_series_statsA | Compact summary of each series (last value, min, max, mean, change) without the raw rows. Use this when you need the numbers for a narrative answer and do not need the full observation history. |
| query_cacheA | Run read-only SQL across every cached series (DuckDB over parquet files). Example: SELECT series_name, avg(value) FROM cached_series WHERE ref_date >= DATE '2020-01-01' GROUP BY 1 ORDER BY 2 DESC. |
| cache_statusA | Report what is cached locally: series, coverage ranges, row counts and disk usage. |
| clear_cacheA | Delete cached parquet files, either for selected series or everything. |
| todayA | Current date on the server, useful for building relative date ranges. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| macro_briefing | Build a short Brazilian macro briefing from a set of SGS series. |
| compare_series | Compare two or more SGS series over time using the local cache. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| SGS dictionary categories | Categories of the bundled BCB-SGS series dictionary. |
| SGS series dictionary | Full curated dictionary of Brazilian macro series (id, name, unit, frequency, source, description, aliases). |
| Local parquet cache status | What is cached locally: series, coverage, rows and disk usage. |
TDQS
Scored across 10 tools
Most tools have clearly distinct purposes across search, metadata, data retrieval, stats, and cache management. Minor potential confusion exists between list_series and search_series, and between describe_series and get_series_stats, but the descriptions make the intended use cases reasonably clear.
The set mostly follows a predictable verb_noun pattern (describe_series, search_series, get_series, clear_cache, list_categories, query_cache). A few names deviate from that pattern, notably cache_status and today, but the overall convention remains readable and consistent.
Ten tools are well scoped for a BCB-SGS data access server. Each tool supports a distinct part of the discover-fetch-inspect-cache workflow without obvious redundancy.
The surface covers the full lifecycle: dictionary search and browsing, metadata inspection, series download, compact statistics, ad hoc SQL over cached data, and cache inspection/clearing. For a read-oriented macro data retrieval server, no obvious operational gap remains.