# 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