Bullrun-mcp is the public metadata and connection documentation repository for the Bullrun hosted MCP connector. Bullrun is primarily a hosted service—normal use requires nothing to be installed and no API keys to be managed. Users simply point their MCP client at the remote endpoint and sign in with Google. This repository contains the connector's public metadata (server.json), connection documentation, and a local stdio build of the MCP layer for directory/security checks. The Bullrun application and data services are maintained separately.
Purpose The connector turns Claude (and other MCP clients) into a research analyst covering global equities, ETFs, company risk, the global macro backdrop, and the user's own portfolio, with Bullrun's own machine learning valuation model built in.
Key capabilities
- Bullrun valuation model: Bullrun's own LightGBM model, which rescores the global equity universe every night. The valuation model predicts the P/E ratio at which fundamentally similar businesses typically trade one year later (or price-to-sales for unprofitable companies); the gap is the model's typical multiple relative to the current multiple minus one. The forecast model is a relative 1-year return ranking signal. Both run on quarterly and annual financial data, so most non-US companies are covered as well. The valuation gap describes how a stock is priced relative to fundamentally similar companies. In walk-forward testing, it did not predict future returns, and the tools state this in every response: it is background information for decisions, not a price target.
- Company risk and relationships: risk bands are Contained → Normal → Elevated → Stretched → Acute, describing measured stress, never a buy/sell opinion. Dials with no reading are reported as unmeasured, not safe.
- Global markets and macro: built for the way European investors actually pick funds—by ISIN, by tracked index, by total cost—and merges duplicate listings of the same fund across multiple exchanges, so a fund listed on six exchanges appears as one choice rather than six.
- Personal portfolio: optional starting points are offered in the client prompt menu: stock_deep_dive (fundamentals, valuation model, risk dials, and relationships for a single ticker), market_briefing (markets, macro, and this week's risk changes), build_portfolio, suggest_positions, and analyze_portfolio.
How to use 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; click Connect and complete the Google sign-in/authorization steps. Full setup for Cursor, VS Code, and MCP Inspector is in docs/mcp-connect.md. Public market data tools are available to any connected client. Portfolio tools resolve the user's own Bullrun account after Google sign-in; the two draft tools require a Bullrun Pro account. Successful research results include contextual links to matching pages on Bullrun. Stock screener links preserve normalized filters, reporting window, listing scope, and sorting. Risk dashboard links preserve mechanism, multiple intervals, coverage, and sorting. Link descriptions disclose settings that the target page cannot reproduce. Clients receive platformLink (label, url, description), webPage, readable Markdown, and MCP resource_link; whether the assistant displays links depends on the client. Saved portfolio drafts link directly to the exact pending draft. Sign-in preserves the destination, and accepting or discarding drafts remains the user's choice. Opening a link never changes positions. Links carry a fixed activity label and source tool name, and contain no tokens, account identity, portfolio values, or free-text briefs. Website activity and completed tool calls are metered separately from upstream API requests. Run npm test for the connector's URL, telemetry, authentication, and integration checks, or npm run test:links for targeted handoff checks.
When to use For example: "By Bullrun's valuation model, is ASML expensive? What is its biggest risk?" "Who are Apple's suppliers, and which of them depend on Apple for most of their revenue?" "Which large US companies currently have stretched or acute leverage?" "Brief me on global markets this morning, with a focus on Europe." "Rank G7 countries by government debt and show Italy's 10-year yield since 2010." "Find the cheapest German stocks relative to fundamentals." Continue research in Bullrun: explore company charts and networks, adjust stock screeners, compare funds, or open macro charts from existing answers.
Limitations Valuation gaps did not predict future returns in forward testing. Risk intervals are only a measurement of stress, not a buy or sell opinion. No reading is reported as not measured. Portfolio tools require Google sign-in to resolve the account; the two draft tools require Bullrun Pro account. Portfolio and draft tools on the hosted endpoint require a Bullrun OAuth token and return an authentication-required error in anonymous stdio checks. Public market data tools require no credentials.
Authentication and privacy This server is an OAuth 2.0 protected resource (RFC 9728). On first connection, the client runs an automatic discovery handshake and guides the user through Google sign-in; after authorization, per-user tools resolve their Bullrun account. The MCP layer is a thin proxy with no database of its own—read tools return market data and the user's own positions, per-user read tools accept privacyMode (default full, or weights_only to return only relative numbers), and draft tools never change live positions. See the privacy policy for details.
Local stdio build The hosted endpoint above is the recommended integration method. For directories that need to build and run a local MCP server, this repository can run the MCP layer via stdio. Public market data tools require no credentials. Portfolio and draft tools still require a Bullrun OAuth token in hosted clients and return an authentication-required error in anonymous stdio checks.
