io.github.viniciuslazzari/bolsai-mcp
Brazilian stock market data (B3, CVM, BCB) for AI assistants: quotes, fundamentals, dividends, FIIs.
Open source Open in the app JSON README (API)
About
Brazilian stock market data (B3, CVM, BCB) for AI assistants: quotes, fundamentals, dividends, FIIs.
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- viniciuslazzari
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.4
- Last push
- 2026-07-07T12:47:03Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:01:38
- Updated
- 2026-08-29 04:01:38
- Origin id
io.github.viniciuslazzari/bolsai-mcp
README
# Bolsai - MCP Server
<!-- mcp-name: io.github.viniciuslazzari/bolsai-mcp -->
Brazilian financial market data for AI assistants. Query stock prices, fundamentals, dividends, FIIs, and macro indicators from the Brazilian market (B3, CVM, BCB) directly from Claude.
## Quick Start
1. Get a free API key at [usebolsai.com](https://usebolsai.com)
2. Install:
```bash
pip install bolsai-mcp
```
3. Add to Claude Desktop (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"bolsai": {
"command": "uvx",
"args": ["bolsai-mcp"],
"env": {
"BOLSAI_API_KEY": "sk_your_key_here"
}
}
}
}
```
Or for Claude Code (`.mcp.json`):
```json
{
"mcpServers": {
"bolsai": {
"command": "bolsai-mcp",
"env": {
"BOLSAI_API_KEY": "sk_your_key_here"
}
}
}
}
```
## Tools
| Tool | Description | Example Prompt |
|------|-------------|----------------|
| `get_stock_quote` | Current price, daily change, 52w range | "What's PETR4 trading at?" |
| `get_fundamentals` | 27+ indicators: P/L, P/VP, ROE, margins | "Show me VALE3 fundamentals" |
| `compare_stocks` | Side-by-side comparison of up to 5 stocks | "Compare PETR4 vs VALE3 vs ITUB4" |
| `get_dividends` | Dividend yield, annual summary, payments | "What dividends did BBDC4 pay?" |
| `search_companies` | Find companies by name or sector | "Find banks listed on B3" |
| `get_price_history` | OHLCV prices since 1986 with adjustments | "PETR4 prices last month" |
| `get_fii_details` | FII fundamentals + distributions | "Show me HGLG11" |
| `get_macro_indicator` | SELIC, IPCA, CDI, USD/BRL | "What's the current SELIC rate?" |
| `get_financial_statements` | Raw CVM income/balance/cash flow | "PETR4 income statement 2024" |
| `screen_stocks` | Filter stocks by metrics | "Find stocks with DY > 8%" |
## Example Conversations
**"What's PETR4 trading at?"**
```
PETR4
Price: R$ 36.19
Change: +R$ 0.53 (+1.49%)
Date: 2024-12-30
52-week: R$ 28.44 – R$ 42.15
YTD: +12.34%
```
**"Compare PETR4 vs VALE3"**
```
Comparison: PETR4 vs VALE3
Metric PETR4 VALE3
─────────────────────────────────────
P/L 4.89 5.23
P/VP 1.12 1.45
EV/EBITDA 3.21 3.87
ROE 33.20% 27.70%
Net Margin 24.50% 23.10%
DY 12.30% 9.90%
Price R$ 36.19 R$ 58.42
```
## Data Coverage
- **350+ stocks** listed on B3
- **400+ FIIs** (Real Estate Investment Funds)
- **40 years** of price history (since 1986)
- **15+ years** of fundamentals (since 2010)
- **27 indicators** including P/L, P/VP, EV/EBITDA, ROE, ROIC, margins
- **Macro data**: SELIC, IPCA, CDI, USD/BRL
- **Updated daily** from official sources (B3, CVM, BCB)
## Configuration
| Environment Variable | Required | Default | Description |
|---------------------|----------|---------|-------------|
| `BOLSAI_API_KEY` | Yes | — | API key from usebolsai.com |
| `BOLSAI_BASE_URL` | No | `https://usebolsai.com/api/v1` | API base URL |
## API Tiers
- **Free**: 200 requests/day. Stock quotes, current fundamentals, company search.
- **Pro** (R$ 49/month): 10,000 requests/day. All tools including history, dividends, financials, macro.
## Development
```bash
cd mcp-server
pip install -e ".[dev]"
pytest
ruff check . && ruff format .
```
## License
MIT