Global stock research, ML forecasts, valuation signals, screeners & portfolio tracking in Claude
Stock research and forecasting with ML predictions, valuation signals, and portfolio tracking.
Captured live from the server via tools/list.
screen_stocks
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.
Parameters (15)
sectorstring
Exact sector name to filter by, e.g. "Technology", "Healthcare". Omit for all sectors.
industrystring
Exact industry name to filter by, e.g. "Software - Infrastructure". Omit for all industries.
countrystring
Exact country name to filter by, e.g. "United States", "Germany". Omit for all countries.
countriesarray
Exact country names to include. Use this for multi-country screens; it overrides country when provided.
lookbackModestring
Whether rule evaluation uses annual or quarterly reporting periods.
lookbackinteger
How many reporting periods to evaluate. Growth rules need at least 2 comparable periods.
modestring
Deprecated alias for lookbackMode; kept for compatibility.
periodsinteger
Deprecated alias for lookback; kept for compatibility.
rulesarray
Fundamental rules. Same groupId means AND; different groupIds mean OR.
minMarketCapnumber
Compatibility shortcut: adds marketCap >= this absolute value to every rule group.
includeSecondaryboolean
Include secondary cross-listings of the same security. Default false (primary listings only).
includeInactiveboolean
Include delisted/inactive tickers with no recent price bar. Default false.
sortBystring
Metric to sort by. revenueGrowth is accepted as an alias for revenueGrowthPct.
orderstring
Sort direction. Nulls always sort last regardless of direction.
limitinteger
Maximum number of stocks to return (1-100).
query_etfs
Search the Bullrun ETF universe by ticker/fund name plus ETF category, focus, domicile, exchange and currency. For an exact ticker, returns ETF profile details, recent historical price rows, and latest holdings. Read-only.
Parameters (13)
searchstring
Free-text ETF search by ticker or fund name. Omit to list the first ETFs.
tickerstring
Exact ETF ticker for profile, prices, and optional holdings, e.g. SPY, VWRL.L, EUNL.DE.
categorystring
Exact ETF category filter. This maps to Bullrun's ETF category column.
focusstring
Exact ETF focus filter. This maps to Bullrun's ETF focus / asset-class column.
domicilestring
Exact ETF domicile filter.
exchangestring
Exact exchange filter, e.g. NYSE ARCA, LSE, XETRA.
currencystring
Exact trading currency filter, e.g. USD, EUR, CHF.
includeSecondaryboolean
Include secondary/cross-listed ETF tickers. Default false.
includeInactiveboolean
Include ETFs with no recent price bar. Default false.
includeHoldingsboolean
When ticker is supplied, include latest holdings. Ignored for broad searches.
holdingsLimitinteger
Maximum holdings to return for an exact ticker, 1-100.
priceLimitinteger
Recent daily price rows to return for an exact ticker. Use 0 to skip prices.
limitinteger
Maximum ETF search rows to return, 1-100.
get_stock_metrics
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 (Yahoo-style suffixes, e.g. AAPL, ABBN.SW, BMW.DE). Read-only.
Parameters (1)
tickerstringrequired
The stock ticker exactly as listed on Bullrun, e.g. "AAPL", "ABBN.SW", "BMW.DE".
get_financial_history
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.
Parameters (4)
tickerstringrequired
The ticker exactly as listed on Bullrun, e.g. "AAPL", "ABBN.SW", "BMW.DE".
periodTypestring
Return annual rows, quarterly rows, or both. Annual rows use fiscalQuarter=0.
yearsinteger
How many fiscal years of history to return, counting backward from the latest fiscal year available.
includeEmptyRowsboolean
Include sparse rows that have no major income statement, balance sheet, cash-flow, or EPS values.
get_quality_moat_metrics
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.
Parameters (4)
tickerstringrequired
The ticker exactly as listed on Bullrun, e.g. "AAPL", "ABBN.SW", "BMW.DE".
yearsinteger
How many fiscal years of annual history to evaluate.
estimatedWaccPctnumber
Optional user-supplied WACC assumption, in percent. When omitted, ROIC-vs-WACC spread is returned as null.
taxRateFallbackPctnumber
Fallback tax rate used for NOPAT only when reported tax/pretax data is missing or unusable.
get_forward_estimates
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.
Parameters (3)
tickerstringrequired
The ticker exactly as listed on Bullrun, e.g. "AAPL", "CRWD", "SPGI".
periodTypestring
Return annual estimates, quarterly estimates, or both.
limitinteger
Maximum estimate rows to return.
get_operating_kpis
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.
Parameters (4)
tickerstringrequired
The ticker exactly as listed on Bullrun, e.g. "CRWD", "SNOW", "V".
metricKeystring
Optional exact metric key to filter, e.g. ARR, NRR, RPO, BILLINGS, PAYMENT_VOLUME.
categorystring
Optional category filter such as SaaS, payments, marketplace, banking, or other domain labels.
limitinteger
Maximum KPI rows to return.
get_revenue_breakdown
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.
Parameters (3)
tickerstringrequired
The ticker exactly as listed on Bullrun, e.g. "SPGI", "MSFT", "V".
dimensionstring
Breakdown dimension to return, or all dimensions.
limitinteger
Maximum breakdown rows to return.
get_earnings_call_transcript
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.
Parameters (6)
tickerstringrequired
The ticker exactly as listed on Bullrun, e.g. "CRWD", "SPGI", "V".
fiscalYearinteger
Optional fiscal year filter.
fiscalQuarterinteger
Optional fiscal quarter filter.
searchstring
Optional case-insensitive text/speaker search across transcript chunks.
maxChunksinteger
Maximum speaker-tagged transcript chunks to return.
maxCharsPerChunkinteger
Maximum characters per transcript chunk in the MCP response.
list_portfolios
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.
Parameters (1)
privacyModestring
"full" (default) includes absolute $; "weights_only" hides cash/value/cost-basis and keeps only %.
get_portfolio_context
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.
Parameters (3)
portfolioIdintegerrequired
The portfolio id, as returned by list_portfolios.
daysinteger
Insights look-back window in days (default 30).
privacyModestring
"full" (default) includes absolute $; "weights_only" returns only relative figures.
get_portfolio_analytics
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.
Parameters (5)
portfolioIdintegerrequired
The portfolio id, as returned by list_portfolios.
daysinteger
Calendar-day lookback for daily USD return analytics. Default 370.
candidateTickerstring
Optional exact Bullrun ticker to test as a candidate diversifier, e.g. AAPL, NESN.SW, BMW.DE.
candidateWeightPctnumber
Optional hypothetical candidate allocation for pro-forma volatility. Default 5 (%).
privacyModestring
"full" (default) includes absolute USD amounts; "weights_only" returns only relative figures.
create_portfolio_draft
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 universe. 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.
Parameters (3)
promptstring
What kind of portfolio to draft, e.g. "a defensive dividend portfolio of large EU stocks". Optional: if you omit it, the server collects a quick style/region/size brief from the user directly (a native form on clients that support elicitation; otherwise it asks you to gather those first).
startingCashnumber
Starting cash in USD (default 10000).
maxPositionsinteger
Maximum number of holdings (3-20, default 10).
create_position_draft
Use when the user asks what to BUY or ADD to an EXISTING portfolio — e.g. "what should I buy next", "suggest a stock 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. 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.
Parameters (2)
portfolioIdintegerrequired
The Bullrun portfolio id to propose additions for. Use list_portfolios first if unsure.
maxPositionsinteger
How many suggested additions to save, 1-5. Use 1 for a single-position idea; default 3.
Bullrun is primarily a hosted service — there is nothing to install and no API key to
manage for normal use. You point your MCP client at the remote endpoint and sign in with
Google. This repository holds the connector's public metadata (server.json),
connection docs, and a local stdio build of the MCP layer for directory/security checks. The
Bullrun application and data services remain maintained separately.
Connect
Claude (web, Desktop, mobile) — requires a paid Claude plan:
Settings → Connectors → Add custom connector
Name it Bullrun, paste https://mcp.bull-run.org/mcp, and add it.
Click Connect and complete the Google sign-in / authorize step.
Claude Code:
bash
claude mcp add --transport http bullrun https://mcp.bull-run.org/mcp
Full setup for Cursor, VS Code, and the MCP Inspector is in
docs/mcp-connect.md.
What you can do once connected
Public market-data tools work for any connected client. The portfolio tools resolve your own
Bullrun account after Google sign-in; the two draft tools require a Bullrun Pro account.
Tool
What it does
screen_stocks
Screen the global universe by sector / industry / country / market cap; sort by P/E, dividend yield, revenue or revenue growth.
get_stock_metrics
Consolidated snapshot for one ticker — identity (ISIN/LEI/CIK), latest price, valuation, most recent financials, description.
get_financial_history
1–15 fiscal years of annual/quarterly statements, per-share metrics, margins, CAGRs and consistency checks.
Draft a new paper portfolio from a plain-English brief. Draft-only — saved for review, never changes a live position. (Pro)
create_position_draft
Suggest additions to an existing portfolio. Draft-only — saved for review. (Pro)
Authentication & privacy
The server is an OAuth 2.0 protected resource (RFC 9728). On first connect your client runs an
automatic discovery handshake and sends you through Google sign-in; after you authorize, per-user
tools resolve your Bullrun account. The MCP layer is a thin proxy with no database of its own —
read tools return market data and your own holdings, the per-user read tools accept a privacyMode
(full by default, or weights_only to return only relative figures), and the draft tools never
mutate live holdings. See the privacy policy.
Local stdio build
The hosted endpoint above is the recommended integration. For directories that require building
and running a local MCP server, this repo can run the MCP layer over stdio:
bash
npm ci
npm run build
BULLRUN_API_BASE=https://bull-run.org node dist/stdio.js
Public market-data tools work without credentials. Portfolio and draft tools still require a
Bullrun OAuth token in hosted clients and return an authentication-required error in anonymous
stdio checks.
