bcb-br-mcp 1.0.1 → 1.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +394 -303
- package/README.pt-BR.md +388 -0
- package/dist/index.js +101 -541
- package/dist/index.js.map +1 -1
- package/dist/tools.d.ts +280 -0
- package/dist/tools.d.ts.map +1 -0
- package/dist/tools.js +725 -0
- package/dist/tools.js.map +1 -0
- package/dist/worker.d.ts +20 -0
- package/dist/worker.d.ts.map +1 -0
- package/dist/worker.js +236 -0
- package/dist/worker.js.map +1 -0
- package/package.json +5 -2
package/README.md
CHANGED
|
@@ -1,303 +1,394 @@
|
|
|
1
|
-
# BCB BR MCP Server
|
|
2
|
-
|
|
3
|
-
[](https://www.npmjs.com/package/bcb-br-mcp)
|
|
4
|
-
[](https://www.npmjs.com/package/bcb-br-mcp)
|
|
4
|
+
[](https://www.npmjs.com/package/bcb-br-mcp)
|
|
5
|
+
[](https://smithery.ai/server/@sidneybissoli/bcb-br-mcp)
|
|
6
|
+
[](https://registry.modelcontextprotocol.io)
|
|
7
|
+
[](https://lobehub.com/mcp/sidneybissoli-bcb-br-mcp)
|
|
8
|
+
[](https://opensource.org/licenses/MIT)
|
|
9
|
+
|
|
10
|
+
[Leia em Português](README.pt-BR.md)
|
|
11
|
+
|
|
12
|
+
MCP (Model Context Protocol) server for accessing the Brazilian Central Bank's time series data (SGS/BCB).
|
|
13
|
+
|
|
14
|
+
Query economic and financial indicators such as **Selic** (interest rate), **IPCA** (inflation), **exchange rates**, **GDP**, and more, directly from AI assistants like Claude.
|
|
15
|
+
|
|
16
|
+
## Features
|
|
17
|
+
|
|
18
|
+
- **Historical data** - Query time series values by code with date filters
|
|
19
|
+
- **Latest values** - Get the most recent N values of any series
|
|
20
|
+
- **Metadata** - Detailed information about series (frequency, source, etc.)
|
|
21
|
+
- **Popular series catalog** - 150+ economic indicators organized in 12 categories
|
|
22
|
+
- **Smart search** - Find series by keyword (accent-insensitive)
|
|
23
|
+
- **Current indicators** - Latest values for key economic indicators
|
|
24
|
+
- **Variation calculation** - Percentage change between periods with statistics
|
|
25
|
+
- **Series comparison** - Compare multiple series over the same period
|
|
26
|
+
|
|
27
|
+
## Available Tools
|
|
28
|
+
|
|
29
|
+
| Tool | Description |
|
|
30
|
+
|------|-------------|
|
|
31
|
+
| `bcb_serie_valores` | Query series values by code and date range |
|
|
32
|
+
| `bcb_serie_ultimos` | Get the last N values of a series |
|
|
33
|
+
| `bcb_serie_metadados` | Get series metadata (name, frequency, source) |
|
|
34
|
+
| `bcb_series_populares` | List popular series grouped by category |
|
|
35
|
+
| `bcb_buscar_serie` | Search series by name or description (accent-insensitive) |
|
|
36
|
+
| `bcb_indicadores_atuais` | Latest values: Selic, IPCA, USD/BRL, IBC-Br |
|
|
37
|
+
| `bcb_variacao` | Calculate percentage variation between dates or last N periods |
|
|
38
|
+
| `bcb_comparar` | Compare 2 to 5 series over the same period with ranking |
|
|
39
|
+
|
|
40
|
+
## Installation
|
|
41
|
+
|
|
42
|
+
### Via Smithery (recommended)
|
|
43
|
+
|
|
44
|
+
Visit [bcb-br-mcp on Smithery](https://smithery.ai/server/@sidneybissoli/bcb-br-mcp) and follow the installation instructions for your MCP client.
|
|
45
|
+
|
|
46
|
+
### Via URL (Claude.ai, Claude Desktop, any MCP client)
|
|
47
|
+
|
|
48
|
+
Use the HTTP endpoint directly, no installation required:
|
|
49
|
+
|
|
50
|
+
```
|
|
51
|
+
https://bcb.sidneybissoli.workers.dev
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
### Via npx (Claude Desktop)
|
|
55
|
+
|
|
56
|
+
Add to your Claude Desktop configuration file:
|
|
57
|
+
|
|
58
|
+
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
|
|
59
|
+
|
|
60
|
+
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
61
|
+
|
|
62
|
+
```json
|
|
63
|
+
{
|
|
64
|
+
"mcpServers": {
|
|
65
|
+
"bcb-br": {
|
|
66
|
+
"command": "npx",
|
|
67
|
+
"args": ["-y", "bcb-br-mcp"]
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### Via global install
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
npm install -g bcb-br-mcp
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
```json
|
|
80
|
+
{
|
|
81
|
+
"mcpServers": {
|
|
82
|
+
"bcb-br": {
|
|
83
|
+
"command": "bcb-br-mcp"
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
## Usage Examples
|
|
90
|
+
|
|
91
|
+
### Get the current Selic rate
|
|
92
|
+
|
|
93
|
+
```
|
|
94
|
+
What is the current Selic interest rate?
|
|
95
|
+
→ Uses bcb_indicadores_atuais
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### IPCA history for 2024
|
|
99
|
+
|
|
100
|
+
```
|
|
101
|
+
Show me the monthly IPCA for 2024
|
|
102
|
+
→ Uses bcb_serie_valores with code 433, dataInicial 2024-01-01, dataFinal 2024-12-31
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
### List inflation indicators
|
|
106
|
+
|
|
107
|
+
```
|
|
108
|
+
What inflation series are available?
|
|
109
|
+
→ Uses bcb_series_populares with category "Inflação"
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
### Search for USD exchange rate series
|
|
113
|
+
|
|
114
|
+
```
|
|
115
|
+
Search for series related to the dollar
|
|
116
|
+
→ Uses bcb_buscar_serie with term "dolar" (works without accents)
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
### Calculate USD/BRL variation
|
|
120
|
+
|
|
121
|
+
```
|
|
122
|
+
What was the USD/BRL variation over the last 12 months?
|
|
123
|
+
→ Uses bcb_variacao with code 1 and periodos 12
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
### Compare IPCA, IGP-M, and INPC
|
|
127
|
+
|
|
128
|
+
```
|
|
129
|
+
Compare IPCA, IGP-M, and INPC in 2024
|
|
130
|
+
→ Uses bcb_comparar with codes [433, 189, 188], dataInicial 2024-01-01, dataFinal 2024-12-31
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
## Series Catalog (150+)
|
|
134
|
+
|
|
135
|
+
The server includes a catalog of 150+ series organized in 12 categories.
|
|
136
|
+
|
|
137
|
+
### Interest Rates
|
|
138
|
+
|
|
139
|
+
| Code | Description |
|
|
140
|
+
|------|-------------|
|
|
141
|
+
| 11 | Selic rate - monthly accumulated |
|
|
142
|
+
| 432 | Selic rate - annualized (base 252) |
|
|
143
|
+
| 1178 | Selic target rate (Copom) |
|
|
144
|
+
| 12 | CDI daily rate |
|
|
145
|
+
| 4389 | CDI annualized (base 252) |
|
|
146
|
+
| 226 | Reference Rate (TR) - daily |
|
|
147
|
+
| 256 | Long-Term Interest Rate (TJLP) |
|
|
148
|
+
|
|
149
|
+
### Inflation (30+ series)
|
|
150
|
+
|
|
151
|
+
| Code | Description |
|
|
152
|
+
|------|-------------|
|
|
153
|
+
| 433 | IPCA - Monthly change |
|
|
154
|
+
| 13522 | IPCA - 12-month accumulated |
|
|
155
|
+
| 7478 | IPCA-15 - Monthly change |
|
|
156
|
+
| 188 | INPC - Monthly change |
|
|
157
|
+
| 189 | IGP-M - Monthly change |
|
|
158
|
+
| 190 | IGP-DI - Monthly change |
|
|
159
|
+
| 7447 | IGP-10 - Monthly change |
|
|
160
|
+
| 10841-10850 | IPCA by group (Food, Housing, Transportation, etc.) |
|
|
161
|
+
| 4449 | IPCA - Administered prices |
|
|
162
|
+
| 11428 | IPCA - Market prices |
|
|
163
|
+
| 16121-16122 | IPCA - Core measures |
|
|
164
|
+
|
|
165
|
+
### Exchange Rates (15+ series)
|
|
166
|
+
|
|
167
|
+
| Code | Description |
|
|
168
|
+
|------|-------------|
|
|
169
|
+
| 1 | USD/BRL - US Dollar (sell) |
|
|
170
|
+
| 10813 | USD/BRL - US Dollar (buy) |
|
|
171
|
+
| 3698/3697 | USD/BRL PTAX (sell/buy) |
|
|
172
|
+
| 21619/21620 | EUR/BRL - Euro (sell/buy) |
|
|
173
|
+
| 21623/21624 | GBP/BRL - British Pound (sell/buy) |
|
|
174
|
+
| 21621/21622 | JPY/BRL - Japanese Yen (sell/buy) |
|
|
175
|
+
| 21637/21638 | ARS/BRL - Argentine Peso (sell/buy) |
|
|
176
|
+
| 21639/21640 | CNY/BRL - Chinese Yuan (sell/buy) |
|
|
177
|
+
|
|
178
|
+
### Economic Activity (25+ series)
|
|
179
|
+
|
|
180
|
+
| Code | Description |
|
|
181
|
+
|------|-------------|
|
|
182
|
+
| 4380 | Monthly GDP (R$ millions) |
|
|
183
|
+
| 4382 | GDP - 12-month accumulated (R$ millions) |
|
|
184
|
+
| 4385 | Monthly GDP in USD |
|
|
185
|
+
| 7324 | Annual GDP in USD |
|
|
186
|
+
| 24363/24364 | IBC-Br Economic Activity Index (unadjusted/seasonally adjusted) |
|
|
187
|
+
| 29601-29606 | IBC-Br by sector (Agriculture, Industry, Services) |
|
|
188
|
+
| 22099 | Quarterly GDP - Rate of change |
|
|
189
|
+
| 21859 | Industrial production - Monthly change |
|
|
190
|
+
| 21862 | Installed capacity utilization |
|
|
191
|
+
|
|
192
|
+
### Employment (10+ series)
|
|
193
|
+
|
|
194
|
+
| Code | Description |
|
|
195
|
+
|------|-------------|
|
|
196
|
+
| 24369 | Unemployment rate - PNAD |
|
|
197
|
+
| 24370 | Labor force participation rate |
|
|
198
|
+
| 24380 | Average real income |
|
|
199
|
+
| 24381 | Real income mass |
|
|
200
|
+
| 28561 | CAGED - Formal job creation |
|
|
201
|
+
|
|
202
|
+
### Fiscal (10+ series)
|
|
203
|
+
|
|
204
|
+
| Code | Description |
|
|
205
|
+
|------|-------------|
|
|
206
|
+
| 4503 | Net public sector debt (% GDP) |
|
|
207
|
+
| 4513 | General government gross debt (% GDP) |
|
|
208
|
+
| 4537 | Primary balance (% GDP) |
|
|
209
|
+
| 4539 | Nominal balance (% GDP) |
|
|
210
|
+
| 5364 | Central government total revenue |
|
|
211
|
+
|
|
212
|
+
### External Sector (15+ series)
|
|
213
|
+
|
|
214
|
+
| Code | Description |
|
|
215
|
+
|------|-------------|
|
|
216
|
+
| 3546 | International reserves - daily |
|
|
217
|
+
| 22707 | Trade balance - Monthly |
|
|
218
|
+
| 22708 | Exports - Monthly |
|
|
219
|
+
| 22709 | Imports - Monthly |
|
|
220
|
+
| 22701 | Current account - Balance |
|
|
221
|
+
| 22846 | Foreign direct investment |
|
|
222
|
+
| 13690 | Total external debt |
|
|
223
|
+
|
|
224
|
+
### Credit (30+ series)
|
|
225
|
+
|
|
226
|
+
| Code | Description |
|
|
227
|
+
|------|-------------|
|
|
228
|
+
| 20539 | Total credit balance |
|
|
229
|
+
| 20540/20541 | Credit balance - Individuals/Corporations |
|
|
230
|
+
| 20714 | Average interest rate - Total |
|
|
231
|
+
| 20749 | Average rate - Vehicle financing |
|
|
232
|
+
| 20772 | Average rate - Mortgage |
|
|
233
|
+
| 20783 | Average spread - Total |
|
|
234
|
+
| 21082 | Default rate - Total |
|
|
235
|
+
| 21128/21129 | Default rate - Credit card |
|
|
236
|
+
|
|
237
|
+
### Monetary Aggregates
|
|
238
|
+
|
|
239
|
+
| Code | Description |
|
|
240
|
+
|------|-------------|
|
|
241
|
+
| 1788 | Monetary base |
|
|
242
|
+
| 27788-27791 | Money supply M1, M2, M3, M4 |
|
|
243
|
+
| 27815 | Money multiplier |
|
|
244
|
+
|
|
245
|
+
### Savings
|
|
246
|
+
|
|
247
|
+
| Code | Description |
|
|
248
|
+
|------|-------------|
|
|
249
|
+
| 25 | Savings - Monthly yield |
|
|
250
|
+
| 195 | Savings - Total balance |
|
|
251
|
+
| 7165 | Savings - Net deposits |
|
|
252
|
+
|
|
253
|
+
### Market Indices
|
|
254
|
+
|
|
255
|
+
| Code | Description |
|
|
256
|
+
|------|-------------|
|
|
257
|
+
| 12466 | IMA-B |
|
|
258
|
+
| 12467 | IMA-B5 |
|
|
259
|
+
| 12468 | IMA-B5+ |
|
|
260
|
+
| 7832 | Ibovespa - Monthly |
|
|
261
|
+
|
|
262
|
+
### Expectations (Focus Survey)
|
|
263
|
+
|
|
264
|
+
| Code | Description |
|
|
265
|
+
|------|-------------|
|
|
266
|
+
| 29033/29034 | IPCA expectation (current/next year) |
|
|
267
|
+
| 29035/29036 | Selic expectation (current/next year) |
|
|
268
|
+
| 29037/29038 | GDP expectation (current/next year) |
|
|
269
|
+
| 29039/29040 | Exchange rate expectation (current/next year) |
|
|
270
|
+
|
|
271
|
+
## Finding Other Series
|
|
272
|
+
|
|
273
|
+
The SGS database contains over 18,000 time series. To find codes for other series:
|
|
274
|
+
|
|
275
|
+
1. Visit the [BCB SGS Portal](https://www3.bcb.gov.br/sgspub/)
|
|
276
|
+
2. Search for the desired series
|
|
277
|
+
3. Note the series code
|
|
278
|
+
4. Use that code with this server's tools
|
|
279
|
+
|
|
280
|
+
## Technical Details
|
|
281
|
+
|
|
282
|
+
### Robustness
|
|
283
|
+
|
|
284
|
+
- **Timeout**: 30 seconds per request (prevents hanging)
|
|
285
|
+
- **Auto-retry**: 3 attempts with exponential backoff (1s, 2s, 4s)
|
|
286
|
+
- **Error handling**: Clear error messages
|
|
287
|
+
|
|
288
|
+
### Smart Search
|
|
289
|
+
|
|
290
|
+
The `bcb_buscar_serie` tool normalizes search terms, allowing you to find series even without Portuguese accents:
|
|
291
|
+
|
|
292
|
+
- `"inflacao"` → finds "Inflação"
|
|
293
|
+
- `"cambio"` → finds "Câmbio"
|
|
294
|
+
- `"credito"` → finds "Crédito"
|
|
295
|
+
|
|
296
|
+
## Development
|
|
297
|
+
|
|
298
|
+
### Requirements
|
|
299
|
+
|
|
300
|
+
- Node.js >= 18.0.0
|
|
301
|
+
|
|
302
|
+
### Setup
|
|
303
|
+
|
|
304
|
+
```bash
|
|
305
|
+
git clone https://github.com/SidneyBissoli/bcb-br-mcp.git
|
|
306
|
+
cd bcb-br-mcp
|
|
307
|
+
npm install
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
### Build
|
|
311
|
+
|
|
312
|
+
```bash
|
|
313
|
+
npm run build
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
### Local testing (stdio)
|
|
317
|
+
|
|
318
|
+
```bash
|
|
319
|
+
npm run dev
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
### Local testing (HTTP worker)
|
|
323
|
+
|
|
324
|
+
```bash
|
|
325
|
+
npm run dev:worker
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
Or use the MCP Inspector:
|
|
329
|
+
|
|
330
|
+
```bash
|
|
331
|
+
npx @modelcontextprotocol/inspector npm run dev
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
## BCB API
|
|
335
|
+
|
|
336
|
+
This server uses the Brazilian Central Bank's public API:
|
|
337
|
+
|
|
338
|
+
- **Base endpoint:** `https://api.bcb.gov.br/dados/serie/bcdata.sgs.{code}/dados`
|
|
339
|
+
- **Format:** JSON
|
|
340
|
+
- **Authentication:** None (public API)
|
|
341
|
+
- **Documentation:** [BCB Open Data](https://dadosabertos.bcb.gov.br/)
|
|
342
|
+
|
|
343
|
+
## Changelog
|
|
344
|
+
|
|
345
|
+
### v1.2.0
|
|
346
|
+
|
|
347
|
+
- HTTP endpoint via Cloudflare Workers (`https://bcb.sidneybissoli.workers.dev`)
|
|
348
|
+
- Published on Smithery.ai
|
|
349
|
+
- Refactored: tool logic extracted to `src/tools.ts` (shared between stdio and HTTP)
|
|
350
|
+
|
|
351
|
+
### v1.1.0
|
|
352
|
+
|
|
353
|
+
- New tool `bcb_variacao` for percentage variation calculation
|
|
354
|
+
- New tool `bcb_comparar` for comparing multiple series
|
|
355
|
+
- 30-second timeout on requests
|
|
356
|
+
- Auto-retry with exponential backoff (3 attempts)
|
|
357
|
+
- Normalized search (accent-insensitive)
|
|
358
|
+
- Additional statistics (max, min, average, range)
|
|
359
|
+
|
|
360
|
+
### v1.0.0
|
|
361
|
+
|
|
362
|
+
- Initial release
|
|
363
|
+
- 6 basic tools
|
|
364
|
+
- Catalog with 150+ series
|
|
365
|
+
|
|
366
|
+
## Contributing
|
|
367
|
+
|
|
368
|
+
Contributions are welcome! Please:
|
|
369
|
+
|
|
370
|
+
1. Fork the repository
|
|
371
|
+
2. Create a feature branch (`git checkout -b feature/new-feature`)
|
|
372
|
+
3. Commit your changes (`git commit -m 'Add new feature'`)
|
|
373
|
+
4. Push to the branch (`git push origin feature/new-feature`)
|
|
374
|
+
5. Open a Pull Request
|
|
375
|
+
|
|
376
|
+
## License
|
|
377
|
+
|
|
378
|
+
MIT - see [LICENSE](LICENSE) for details.
|
|
379
|
+
|
|
380
|
+
## Author
|
|
381
|
+
|
|
382
|
+
**Sidney da Silva Pereira Bissoli**
|
|
383
|
+
|
|
384
|
+
- GitHub: [@SidneyBissoli](https://github.com/SidneyBissoli)
|
|
385
|
+
- Email: sbissoli76@gmail.com
|
|
386
|
+
|
|
387
|
+
## Useful Links
|
|
388
|
+
|
|
389
|
+
- [BCB SGS Portal](https://www3.bcb.gov.br/sgspub/)
|
|
390
|
+
- [BCB Open Data](https://dadosabertos.bcb.gov.br/)
|
|
391
|
+
- [Model Context Protocol](https://modelcontextprotocol.io/)
|
|
392
|
+
- [MCP Registry](https://registry.modelcontextprotocol.io/)
|
|
393
|
+
- [Smithery: bcb-br-mcp](https://smithery.ai/server/@sidneybissoli/bcb-br-mcp)
|
|
394
|
+
- [npm: bcb-br-mcp](https://www.npmjs.com/package/bcb-br-mcp)
|