Skip to main content
Glama

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
  1. 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"
      }
    }
  }
}

Related MCP server: big-mcp-b3

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

Available Tools

11 tools
compare_stocksA

Compare fundamental indicators across multiple stocks side by side.

Args: tickers: Comma-separated tickers, 2-5 (e.g. "PETR4,VALE3,ITUB4") metrics: Optional comma-separated metrics to show (e.g. "pl,pvp,roe,dividend_yield"). Available: pl, pvp, ev_ebitda, roe, roa, roic, net_margin, gross_margin, ebitda_margin, dividend_yield, close_price, lpa, vpa, debt_equity, p_sr

Inputs: tickers (required), metrics. Returns: result

get_dividendsA

Get dividend history with yield, annual summary, and individual payments.

Works for both stocks and FIIs. FII tickers (ending in 11) are auto-detected.

Args: ticker: Stock or FII ticker (e.g. PETR4, HGLG11) years: Years of history (1-20, default 3)

Inputs: ticker (required), years. Returns: result

get_fii_detailsA

Get FII (Real Estate Fund) details: P/VP, dividend yield, NAV, and distributions.

Args: ticker: FII ticker (e.g. HGLG11, KNRI11, MXRF11)

Inputs: ticker (required). Returns: result

get_financial_statementsA

Get raw CVM financial statements (income, balance sheet, cash flow).

Args: ticker: Stock ticker (e.g. PETR4) statement_type: DRE (income), BPA (assets), BPP (liabilities), DFC_MI (cash flow), DVA (value added). Default: DRE. report_type: DFP (annual) or ITR (quarterly). Default: DFP. reference_date: Date (YYYY-MM-DD). Default: latest available.

Inputs: ticker (required), report_type, reference_date, statement_type. Returns: result

get_fundamentalsA

Get fundamental indicators: P/L, P/VP, EV/EBITDA, ROE, margins, debt ratios, and more.

Returns 27+ indicators for Brazilian stocks. Uses the latest available data unless a specific reference_date is provided.

Args: ticker: Stock ticker (e.g. PETR4, VALE3) reference_date: Optional date (YYYY-MM-DD) for historical snapshot

Inputs: ticker (required), reference_date. Returns: result

get_macro_indicatorA

Get Brazilian macroeconomic indicator data.

Args: indicator: One of: selic, selic_target, ipca, cdi, usd_brl, eur_brl limit: Number of data points (default 30)

Inputs: indicator (required), limit. Returns: result

get_price_historyA

Get historical OHLCV stock prices with adjusted values for splits and dividends.

Data available from 1986 to present.

Args: ticker: Stock ticker (e.g. PETR4) start: Start date (YYYY-MM-DD) end: End date (YYYY-MM-DD) limit: Max data points (default 30, max 5000)

Inputs: ticker (required), end, limit, start. Returns: result

get_stock_quoteA

Get the current stock price with daily change, 52-week range, and YTD return.

Args: ticker: Brazilian stock ticker (e.g. PETR4, VALE3, ITUB4)

Inputs: ticker (required). Returns: result

list_sectorsA

List all available sectors with company counts.

Use this to discover valid sector names for search_companies and screen_stocks.

Inputs: no named parameters. Returns: result

screen_stocksA

Screen ALL Brazilian stocks by fundamental metrics. Scans ~264 companies in one call.

Args: filters: Comma-separated filters like "pl_lt=15,roe_gt=10,dividend_yield_gt=5". Supported metrics: pl, pvp, ev_ebitda, roe, roa, roic, net_margin, gross_margin, ebitda_margin, dividend_yield, debt_equity, net_debt_ebitda, market_cap, lpa, vpa, current_ratio, p_sr, cagr_revenue_5y, cagr_earnings_5y. Use _gt (greater than) or _lt (less than) suffix. sector: Sector filter (e.g. "Bancos", "Energia Elétrica", "Petróleo e Gás") sort: Sort by metric (default: market_cap). Any filterable metric works. order: "asc" or "desc" (default: desc) limit: Max results (default 20)

Inputs: sort, limit, order, sector, +1 more. Returns: result

search_companiesA

Search for Brazilian listed companies by name or sector.

Use list_sectors first to see valid sector names.

Args: query: Search term for company name (e.g. "Petrobras", "banco") sector: Filter by sector (e.g. "Bancos", "Petróleo e Gás", "Energia Elétrica")

Inputs: query, sector. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 11 tools

    Disambiguation5/5

    Each tool targets a distinct data retrieval or analysis task: comparison, dividends, FII details, financial statements, fundamentals, macro indicators, price history, current quote, sector listing, screening, and company search. No tool overlaps significantly in purpose.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with snake_case. Verbs are descriptive (get_, compare_, list_, screen_, search_) and nouns clearly indicate the resource. No mixing of conventions.

    Tool Count5/5

    11 tools is well-scoped for a Brazilian stock market data server. Each tool addresses a specific need without redundancy, covering the core data retrieval and analysis workflows.

    Completeness5/5

    The toolset covers the full spectrum of fundamental analysis: real-time and historical prices, fundamentals, dividends, financial statements, macro indicators, screening, and company/sector discovery. No obvious gaps for data retrieval purposes.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      MCP server for B3 (Brazilian stock exchange) data, offering tools for real-time quotes, historical prices, dividends, FIIs, fundamental analysis, options, and indices via natural language.
      9
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides AI agents with clean, normalized access to financial data including company fundamentals, insider trades, SEC filings, macro series from FRED, real-time quotes, and ETF holdings.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides point-in-time Brazilian market data and official statistics, enabling accurate backtesting and AI agent access to vintage, unrevised data, as well as Brazilian financial primitives like PIX code generation and business day calculations.
      MIT