mcp server

Bullrun

Global stock research, ML forecasts, valuation signals, screeners & portfolio tracking in Claude

Description as published by the maintainer. Source

• version 0.1.2
• active
• retrieval

active — Registry entry last updated 2026-06-29. Dashed tags are derived by ZBS Index from the published description, not stated by the maintainer.

What this server can do

26 functions, named and described by the server itself. Parameter names are shown because they say more about what a function does than its name usually does.

analyze_etf_overlap(tickers, topSharedLimit)

Compare two to ten ETFs using their latest stored holdings. Returns pairwise shared holdings, weighted overlap (sum of the smaller weight for each shared holding), each fund's weight in shared names, and the largest duplicate exposures. Coverage is explicit because provider holdings may be partial top-holdings samples. Read-only. Required: tickers.

analyze_portfolio_fit(days, portfolioId, candidateTicker, candidateWeightPct, includeLookThrough)

Analyze an ETF candidate against one signed-in user's portfolio. Combines Bullrun's price-history candidate fit (correlation, beta and pro-forma volatility) with latest-holdings look-through that identifies direct and ETF-contained duplicate underlying positions. Coverage is explicit and partial provider holdings make duplicate exposure a lower bound. Requires OAuth read:portfolios. Read-only. Required: portfolioId, candidateTicker.

compare_etfs(include, tickers, performanceDays)

Return a normalized side-by-side comparison of two to ten ETFs across selected classification, market, fund-data, cost, income, benchmark, price-performance, price-risk, and holdings modules. Leaders are mechanical extrema, not recommendations. Currency and partial-holdings caveats are explicit. Read-only. Required: tickers.

create_portfolio_draft(prompt, maxPositions, startingCash, instrumentUniverse)

Use when the user wants you to BUILD or PROPOSE a brand-new portfolio for them — e.g. "build me a portfolio", "put together a dividend portfolio", "draft a portfolio of AI stocks", "create a new portfolio for $10k". Generates a REVIEWABLE paper-portfolio draft for the signed-in Bullrun user from a natural-language brief (e.g. "a diversified European dividend portfolio"). Requires OAuth with the write:drafts scope and a Bullrun Pro account. This is DRAFT-ONLY and never changes any live position: the draft is saved to the user's account and appears in the Bullrun Portfolio tab under "Pending AI drafts", where the user reviews it and explicitly accepts it to create a new portfolio (or discards it). To suggest additions to an EXISTING portfolio instead, use create_position_draft. Tickers are chosen only from Bullrun's priced stock/ETF universe; pass instrumentUniverse for stocks only, ETFs only, or a mix. If the brief is vague, first ask ONE quick round of up to three multiple-choice questions (investing style, region focus, and size), each with a default the user can accept with "just pick for me", then build; skip any dimension the user already specified and do not interrogate across multiple turns.

create_portfolio_from_positions(name, cashPct, positions, startingCash)

Use when YOU (or the user) have ALREADY decided the exact holdings and want them saved as-is — e.g. after researching and settling on a specific basket with target weights. Persists a REVIEWABLE paper-portfolio draft built from the tickers you supply, sized by weight (percent) or by explicit USD amount. Unlike create_portfolio_draft this does NOT use the LLM and NEVER re-selects tickers: your basket lands exactly as given. It is NOT Pro-gated (it mirrors manual position entry, which is free) and needs only OAuth with the write:drafts scope. DRAFT-ONLY: the draft is saved to the user's Bullrun account and appears in the Portfolio tab under "Pending AI drafts", where the user reviews it and explicitly accepts it (creating a NEW portfolio) or discards it — it never changes any live position. Tickers must exist in Bullrun's priced stock/ETF universe; any that cannot be priced are returned in `unresolved` and skipped (use search_etfs / get_etf_snapshot / screen_stocks / get_stock_metrics to confirm exact tickers first). For a vague brief where the model should pick, use create_portfolio_draft instead. Required: positions.

create_position_draft(portfolioId, maxPositions, instrumentUniverse)

Use when the user asks what to BUY or ADD to an EXISTING portfolio — e.g. "what should I buy next", "suggest a stock or ETF for my portfolio", "what should I add", "recommend a position", "any ideas to round out my holdings". Generates REVIEWABLE suggested additions for one existing Bullrun portfolio. Requires OAuth with the write:drafts scope and a Bullrun Pro account. This is DRAFT-ONLY: the suggested position(s) are saved to the user's account and appear in the Bullrun Portfolio tab under Pending AI drafts, where the user reviews and accepts them into the target portfolio or discards them. It never changes live holdings by itself. To draft a whole new portfolio from scratch use create_portfolio_draft; to test whether a specific named ticker fits, use get_portfolio_analytics with candidateTicker. Pass instrumentUniverse for stocks only, ETFs only, or a mix. If it is unclear, first confirm which portfolio (use list_portfolios when the user has more than one) and how many ideas (a single best idea or a few) in ONE quick step; otherwise just build. Required: portfolioId.

get_capabilities

Discover what the connected Bullrun account can do BEFORE attempting an action, so you can plan instead of learning by hitting a 403. Reports whether you are authenticated and as WHICH identity (email + userId), whether the account has Bullrun Pro and why (subscription / trial / admin), the granted OAuth scopes, portfolio usage vs the free/max limits, and a per-tool entitlement map: create_portfolio_from_positions (free), create_portfolio_draft and create_position_draft (Pro-only), and whether another portfolio can be created now. Call this first when a draft/write tool might be gated, or to confirm which account a request will act on. Read-only.

get_earnings_call_transcript(search, ticker, maxChunks, fiscalYear, fiscalQuarter, maxCharsPerChunk)

Fetch speaker-tagged earnings-call transcript chunks for one exact Bullrun ticker, optionally filtered by fiscal period or search text. Use this for management guidance language, analyst Q&A, and qualitative judgment that is not visible in financial statements. Read-only. Required: ticker.

get_etf_exposures(types, ticker, limitPerType)

Calculate sector, country, currency, and broad asset exposure from the latest stored ETF holdings and Bullrun instrument mappings. Factor and thematic look-through are reported unavailable until dedicated source data exists. Coverage states how much fund weight and how many holding symbols were resolved, so partial top-holdings data is never presented as full exposure. Read-only. Required: ticker.

get_etf_holdings(limit, cursor, ticker)

Return the latest stored ETF holdings snapshot with opaque cursor pagination. The response reports the provider's stated holdings count, stored row count, covered weight, and whether the stored rows appear complete. Treat isComplete=false or null as partial look-through data. Historical as-of selection will be added when the upstream API exposes it. Read-only. Required: ticker.

get_etf_risk(days, ticker, benchmarkTicker, riskFreeRatePct)

Calculate drawdown, annualized volatility, downside volatility, historical VaR, Sharpe, Sortino and Calmar ratios from stored daily close prices. With benchmarkTicker, also calculates beta, correlation, tracking error, active return and information ratio on aligned dates. Results are price-return risk, not distribution-adjusted total-return risk. Read-only. Required: ticker.

get_etf_snapshot(ticker, include)

Fetch a modular snapshot for one exact ETF listing. The include array controls which of identity, classification, market, fund_data (NAV/AUM), costs, income, and benchmark are fetched and returned. Unrequested modules are omitted; requested-but-unavailable modules are named explicitly. Ratios use percentage points. Read-only. Required: ticker.

get_etf_timeseries(limit, series, ticker, endDate, interval, startDate, benchmarkTicker)

Fetch ETF price or price-return history at daily, weekly, or monthly intervals. NAV, true total-return, benchmark, and premium/discount series are returned only when their required source data or an explicit benchmark ticker exists; unavailable requested series are named explicitly and never approximated with price returns. Read-only. Required: ticker.

get_financial_history(years, ticker, periodType, includeEmptyRows)

Fetch 1-15 years of historical financial statements for one exact Bullrun ticker. Returns annual and/or quarterly rows grouped into income statement, balance sheet, cash flow, per-share metrics, margins, source currency, and annual growth/CAGR consistency checks. Use this when evaluating multi-year revenue/net-income growth, margin trajectories, leverage, cash flow quality, or whether a stock passed a rule such as 10% revenue and net-income growth every year. Required: ticker.

get_forward_estimates(limit, ticker, periodType)

Fetch forward consensus revenue/EPS/EBITDA estimates, management guidance ranges, and estimate-revision percentages for one exact Bullrun ticker. Also derives simple forward P/E and PEG-style context from the latest close when EPS estimates are available. Read-only. Required: ticker.

get_operating_kpis(limit, ticker, category, metricKey)

Fetch period-specific operating KPIs and unit-economics metrics for one exact Bullrun ticker: ARR, net revenue retention, RPO, billings, customer counts, payments volume, cross-border volume, processed transactions, or other domain-specific metrics when populated. Read-only. Required: ticker.

get_portfolio_analytics(days, portfolioId, privacyMode, candidateTicker, candidateWeightPct)

Use when the user asks about THEIR portfolio's risk, diversification, or concentration, or whether to add a stock — e.g. "is my portfolio diversified", "how risky is my portfolio", "am I too concentrated", "what's my exposure to X", "should I add NVDA", "would AAPL improve my diversification". Fetches portfolio-level relationship analytics for one signed-in user's portfolio: correlation and annualized covariance matrices across holdings, contribution-to-risk, concentration by weight and risk, currency/sector/country exposures, value/growth/momentum/quality/size proxy factor scores, scenario/stress tests (rates +100bp, oil -20%, USD +10%), and optional candidateTicker fit analysis showing correlation to the current portfolio plus pro-forma volatility (set candidateTicker when the user asks whether to add a specific stock). Pass a portfolioId from list_portfolios. The risk math only covers holdings with enough price history, dropping unpriced/unmatched ones (ETFs, funds, untracked tickers) and renormalizing all percentages over what remains; the response leads with a `coverage` banner (first text block) stating how many holdings were excluded, so never read these figures as the whole portfolio. For a plain holdings/value snapshot and the full matched/unmatched breakdown use get_portfolio_context instead. Requires OAuth (read:portfolios) and returns the caller's own data only. privacyMode defaults to "full"; "weights_only" hides absolute USD amounts while keeping weights, percentages, correlations and scores. Required: portfolioId.

get_portfolio_context(days, portfolioId, privacyMode)

Use when the user asks to look at, review, or analyze THEIR portfolio / holdings / positions — e.g. "analyze my portfolio", "how is my portfolio doing", "what's in my portfolio", "review my holdings", "how am I invested", "what should I improve". Fetches a deep snapshot of ONE of the signed-in user's portfolios: the summary (value, day change, total return), every holding (with position weight %, sector and return) and Bullrun's computed insights (benchmark comparison, concentration, diversification, dividend income). Pass a portfolioId from list_portfolios (call that first if the user hasn't named a portfolio). The response ALWAYS returns the complete holdings list with each position flagged matched/unmatched, plus a `coverage` summary: holdings that Bullrun can't link to its universe (ETFs, funds, untracked tickers) carry no weight, sector, insight or ML score, so weights/insights/ML below describe ONLY the matched subset. Read the coverage banner (the first text block) and never present matched-only figures as the whole portfolio. For risk/diversification math, correlations, factor exposure, or whether to add a specific stock, use get_portfolio_analytics instead. Requires OAuth (read:portfolios) and returns the caller's own data only. privacyMode defaults to "full" (absolute $ included); "weights_only" returns only relative figures. Read-only. Required: portfolioId.

get_quality_moat_metrics(years, ticker, estimatedWaccPct, taxRateFallbackPct)

Compute annual quality, moat, earnings-quality, and capital-allocation metrics for one exact Bullrun ticker from existing financial statements: ROIC, ROE/ROA, ROIC-vs-supplied-WACC, accruals, cash conversion, capex intensity, dividend payout/growth, diluted share-count changes, and a buyback proxy. Read-only. Required: ticker.

get_revenue_breakdown(limit, ticker, dimension)

Fetch segment, geography, product, customer, or other revenue breakdown rows for one exact Bullrun ticker. Use this to separate cyclical businesses from recurring segments or inspect geographic exposure instead of relying on blended revenue. Read-only. Required: ticker.

get_stock_metrics(ticker)

Fetch a consolidated metrics snapshot for a single stock by ticker: identity (company, exchange, currency, sector, industry, country, ISIN), latest daily price (OHLCV), latest valuation (market cap, P/E, dividend yield, annual dividend per share), the most recent reported financials (revenue, gross/operating income, EBITDA, net income, diluted EPS, free & operating cash flow, total debt, cash, total assets, equity) and a short company description. Use the exact ticker as listed on Bullrun - the native local-exchange symbol (e.g. AAPL, BMW, ABBN, NESN, or a numeric code like 005930), NOT Yahoo-style country suffixes like BMW.DE or ABBN.SW. If a ticker returns no data, use screen_stocks (by sector/country) to find the exact symbol. Read-only. Required: ticker.

list_portfolios(privacyMode)

Use when the user refers to THEIR portfolio(s) or holdings — e.g. "my portfolios", "what portfolios do I have", "how are my investments doing", "show my holdings", "my account". Lists the signed-in Bullrun user's virtual portfolios with computed summaries: name, base currency, total value (USD), day change, cost basis and total return, plus position counts. Start here when a portfolio question doesn't name a specific portfolio, then pass a portfolioId to get_portfolio_context or get_portfolio_analytics. Requires connecting this server to a Bullrun account (OAuth, read:portfolios scope) — it returns that user's own data only. privacyMode defaults to "full" (includes absolute $ amounts); pass "weights_only" to hide absolute money and return only relative figures (returns %, counts). Read-only.

query_etfs(focus, limit, search, ticker, category, currency, domicile, exchange, priceLimit, holdingsLimit, includeHoldings, includeInactive, includeSecondary)

Compatibility tool for older clients: search the Bullrun ETF universe and optionally bundle profile, recent prices, and latest holdings for an exact ticker. New clients should use search_etfs, get_etf_snapshot, and get_etf_holdings for smaller responses, structured output, quantitative filters, and explicit coverage metadata. Read-only.

screen_stocks(mode, limit, order, rules, sector, sortBy, country, periods, industry, lookback, countries, lookbackMode, minMarketCap, includeInactive, includeSecondary)

Screen the global Bullrun stock universe with the same rule engine as the app screener. Filter by sector, industry, country/countries, primary vs secondary listings, active vs inactive listings, lookback mode, AND/OR rule groups, comparison operators, money units, growth metrics and latest-value metrics. Returns a compact table of matching stocks. Read-only.

search_etfs(focus, limit, minAum, region, search, sortBy, category, currency, domicile, exchange, scanLimit, sortDirection, minYieldTtmPct, includeInactive, includeSecondary, maxExpenseRatioPct)

Discover and screen ETFs by name/ticker, classification, listing, AUM, expense ratio, and yield. Quantitative filters are applied only to profile-enriched candidates and the response always reports scan coverage; do not describe the result as exhaustive when candidateCapReached is true. Use get_etf_snapshot for one fund and get_etf_holdings for constituents. Read-only.

simulate_etf_cost(years, ticker, spreadPct, expenseRatioPct, initialInvestment, commissionPerTrade, contributionAmount, grossAnnualReturnPct, contributionFrequency)

Simulate expense-ratio, assumed bid/ask spread, commissions, and recurring contributions over a holding period. Compares the same gross-return path with and without costs and reports direct charges plus ending-value drag. Taxes, FX, market impact and brokerage-specific fees are excluded unless represented by the inputs. Read-only. Required: ticker.

Last successful function declaration observed on 2026-08-13. Source: https://mcp.bull-run.org/mcp. We list what the server declared; we do not call any of these functions.

Endpoint status observed on 2026-08-13. Source: https://mcp.bull-run.org/mcp.

Signals

These are separate measurements of different things. They are deliberately not combined into one score, because a popularity number that mixes website traffic with saves and stars cannot be checked or acted on.

Where to get it

• Repository — https://github.com/ferinator/bullrun-mcp
• Remote endpoint (streamable-http) — https://mcp.bull-run.org/mcp