Use with Claude¶
Stockdex includes a local, read-only Model Context Protocol (MCP) server, so Claude can look up stock data for you. It provides 24 read-only tools:
search_ticker: find ticker symbols for a company name (Yahoo Finance)get_quotes: current quotes for up to 20 symbols (Yahoo Finance)get_prices: daily open, high, low, close and volume, up to 1 year, or monthly prices going back decades (Yahoo Finance / Digrin)get_financial_statement: annual or quarterly income statement, cash flow, balance sheet or financials (EBITDA, EBIT): up to 5 years from Yahoo Finance or about 15 from Macrotrends (Yahoo Finance / Macrotrends)get_margins_and_ratios: gross, operating, EBITDA, pre-tax and net margin history, key financial ratios and revenue history (Macrotrends)get_quarterly_fundamentals: long quarterly histories of assets, liabilities, cash, debt, free cash flow, net income, expenses and shares outstanding (Digrin)get_key_statistics: market cap, P/E, beta, 52-week range, margins and analyst price targets (Yahoo Finance)get_valuation_history: market cap, enterprise value and valuation ratios over time (Yahoo Finance)get_company_profile: business summary, sector, executives and related tickers (Yahoo Finance)get_revenue_breakdown: annual revenue by business segment, region or product (Finviz)get_analyst_estimates: ePS and revenue estimates, recommendations, rating changes and EPS surprises, plus Zacks consensus surprises, quarterly and yearly forecasts, P/E and growth forecasts (Yahoo Finance / Nasdaq)get_earnings_reaction: price moves around earnings reports, EPS and revenue surprises, estimate revisions and annual EPS and sales since about 2010 (Finviz)get_earnings_calendar: next earnings date, estimates and dividend dates (Yahoo Finance)get_holders: institutional and fund holders, ownership breakdown and insider transactions (Yahoo Finance)get_insider_trades: recent insider buys and sales with price, shares and value (Finviz)get_sec_filings: recent SEC filings with links (Yahoo Finance)get_dividends: dividend history (Digrin by default, Yahoo Finance as an alternative or fallback) (Digrin / Yahoo Finance)get_dividend_metrics: payout ratio and dividend growth projections, and annual dividend, yield and payout, and ex-dividend dates (Digrin / Finviz)get_splits: stock split history (Yahoo Finance / Digrin)get_option_expirations: listed option expiration dates (Yahoo Finance)get_options_chain: calls and puts for one expiration date (Yahoo Finance)get_etf_profile: basics, price, top holdings, countries and sectors of a European ETF by ISIN (justETF)get_fund_holdings: eTF and fund top holdings, sector weights and asset allocation (Yahoo Finance)get_fund_profile: eTF and fund fees, category and performance vs category (Yahoo Finance)
Most data comes from Yahoo Finance. Long statement histories and margins come from Macrotrends, long quarterly fundamentals and dividend metrics from Digrin, revenue breakdowns, insider trades and earnings reactions from Finviz, consensus forecasts from Nasdaq, and European ETF data from justETF.
The server runs on your computer and needs no API key. Requests go to Yahoo Finance, Macrotrends, Digrin, Finviz, Nasdaq and justETF, and results you use in a conversation are sent to Claude.
Claude Desktop (one click)¶
Download
stockdex.mcpbfrom the latest GitHub release.Double-click the file, or drag it into Settings → Extensions in Claude Desktop, and click Install.
Claude Desktop installs Python and the dependencies itself. You don’t need a terminal.
Claude Code (plugin)¶
The plugin adds the MCP server and a skill that tells Claude when and how to use it. It requires uv.
/plugin marketplace add ahnazary/stockdex
/plugin install stockdex@stockdex
Then ask, for example, “How have Apple’s revenue and net income changed over the last five years?”
Other MCP clients¶
Any MCP client that can start a stdio server can run it with uvx:
{
"mcpServers": {
"stockdex": {
"command": "uvx",
"args": ["--from", "stockdex[mcp]", "stockdex-mcp"]
}
}
}
If you’d rather use pip, run pip install "stockdex[mcp]" and set
command to stockdex-mcp.
Command line¶
The same operations are also available as a JSON command-line tool:
pip install stockdex
stockdex-claude prices AAPL --range 3mo --limit 5
stockdex-claude financial-statement AAPL --statement cash_flow --frequency quarterly
stockdex-claude dividends KO
Arguments and limits¶
Tickers use Yahoo symbols, e.g.
AAPL,BRK-B,BMW.DE,^GSPCorGC=F.limit sets how many rows come back (1–500, default 20, newest first). Output is also capped at 256 KiB.
Datasets: tools such as
get_key_statisticsandget_holderstake adatasetargument that selects one view; each tool lists its allowed values and default.Dividends use
sourcedigrin(default),yahooorauto(Digrin, falling back to Yahoo Finance).Prices use
range1mo(default),3mo,6moor1yat a daily interval. These are historical bars, not real-time quotes.Financial statements (
get_financial_statement):statementisincome_statement(default),cash_floworbalance_sheet.frequencyisannual(default) orquarterly.start_dateandend_dateareYYYY-MM-DD; the end date is exclusive.source="yahoo"(default): the window can be at most five years.metricstakes up to 20 names fromstockdex/config.pywithout a prefix, e.g.TotalRevenue, and output columns have anannualorquarterlyprefix, e.g.annualTotalRevenue.source="macrotrends": about 15 years, with no window limit.metricstakes up to 20 Macrotrends row names, e.g.RevenueorNet Income(case-insensitive), and output columns are those names without a prefix. Amounts are in millions of the reporting currency, but per-share figures such as EPS and ratios are not scaled: an EPS of7.46is 7.46 per share.
Reading results¶
Every call returns a JSON envelope. Check ok first, then use
records and columns. The envelope also includes source,
retrieved_at, warnings and truncated. When a call fails,
error.code is one of:
invalid_input: an argument is out of range or malformed.busy: another request is still running.rate_limited: the provider asked to slow down.provider_blocked: the website refused the request, usually because of bot protection. Try anothersourceor try later.layout_changed: a scraped page no longer has the expected structure. This says nothing about the value itself.network_error,no_data,provider_schema_errororprovider_error.Yahoo Finance statement values are raw provider numbers with unknown currency and units. Macrotrends units are described above.
nullmeans the value is missing, not zero.Fractions are not percentages: a yield or margin of
0.031is 3.1%.Only one provider request runs at a time. Respect provider rate limits and terms of use.
The data isn’t guaranteed to be accurate and is not investment advice.
Stockdex is an independent, unofficial project and is not affiliated with, endorsed by, or sponsored by Yahoo, Nasdaq, Digrin, Macrotrends, JustETF, Finviz or any other data provider. Data belongs to its providers; you are responsible for following their terms of use. Intended for personal, research and educational use only.