bolsai-mcp 0.1.0

MCP server for bolsai Brazilian financial data API

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

1. Get a free API key at usebolsai.com

2. Install:

pip install bolsai-mcp

3. 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$ 29/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