bolsai-mcp

Bolsai - MCP Server

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

• Get a free API key at usebolsai.com

• Install:

pip install bolsai-mcp

• Add to Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "bolsai": {
      "command": "uvx",
      "args": ["bolsai-mcp"],
      "env": {
        "BOLSAI_API_KEY": "sk_your_key_here"
      }
    }
  }
}

Or for Claude Code (.mcp.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

cd mcp-server
pip install -e ".[dev]"
pytest
ruff check . && ruff format .

License

MIT