tickerscout-mcp

# Ticker Scout MCP server

An agent-native data layer for SEC filings, over the Model Context Protocol. Finished financial statements for public companies, and the filings themselves read and synthesized. The SEC publishes the numbers as data, but it does not publish them as statements. This serves them already assembled, through 20 tools: any statement for any fiscal year or quarter, any line item by its standard name or the company's own, every fiscal year and quarter held, every accession number cited, and the 10-K, 10-Q and 8-K narrative by section, topic or keyword. No API key, no signup, no paywall.

```
https://mcp.tickerscout.ai/mcp
```

It exposes the data published at tickerscout.ai ([https://tickerscout.ai](https://tickerscout.ai)): financial statements, the annual and quarterly reports read and synthesized, and material event histories for S&P 500 companies and major foreign issuers that file with the SEC, all derived from their own filings.

## What is already done for you

The difference between this and the EDGAR APIs is assembly, not availability. The SEC gives you facts. This gives you statements.

- **The three statements arrive as statements.** Income statement, balance sheet and cash flow, line items in reported order, not a flat bag of tagged facts you have to select concepts for and group yourself.
- **Assembled across filings, because no single filing holds the whole record.** Annual figures come from the annual report, quarterly and year-to-date figures from the quarterly report, and where a quarterly report presents cash flow only on a year-to-date basis, the discrete quarter comes from the earnings release filed as a current-report exhibit. For a US filer that means the 10-K, the 10-Q and the 8-K; for a foreign issuer, the 20-F or 40-F and the 6-K.
- **On the company's own fiscal calendar.** 52- and 53-week years, quarters that are 13-week periods rather than calendar quarters, and fiscal years that do not end in December. Period dates come from the column headings the filings themselves print.
- **In actual dollars and actual shares.** Never thousands, never millions, no scale factor to infer. Share counts are adjusted for splits. A foreign issuer's figures are converted to US dollars at the rate recorded on each period, and per-share figures are per ADS where the company has an ADR program.
- **Shaped to the business.** A bank, an insurer, an asset manager and a retailer do not have the same statements, so they do not get the same sections. Ask what a company has rather than assuming a fixed shape.
- **With the gaps named.** Where a filing does not disclose a figure it is omitted and the omission is explained, never silently zeroed. Every figure cites the SEC accession number it came from.
- **Figures link to the line of the filing that prints them.** Wherever the filing tags a figure, the response carries a sec.gov link that opens the filing at that number.

## Connect

**Claude Code**

```
claude mcp add --transport http ticker-scout https://mcp.tickerscout.ai/mcp
```

**Claude on the web or desktop**

Settings, then Connectors, then Add custom connector, and paste the URL.

**Cursor, and any client with an `mcpServers` config**

```json
{
  "mcpServers": {
    "ticker-scout": {
      "url": "https://mcp.tickerscout.ai/mcp"
    }
  }
}
```

**Clients that only speak stdio**

```json
{
  "mcpServers": {
    "ticker-scout": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.tickerscout.ai/mcp"]
    }
  }
}
```

## Start here

The main six tools answer most questions in one call; the other fourteen each answer one kind of question, and take arguments rather than multiplying into near-duplicates.

| Question | Call |
| --- | --- |
| Is a company covered? What is its ticker? | `list_companies(query)` |
| How did it do last quarter? | `get_key_figures(ticker)` |
| Any line item, one or several at once | `get_figure(ticker, "revenue")`, `get_figure(ticker, ["revenue", "net income", "eps"])` |
| A figure's full history | `get_figure(ticker, "free cash flow", period: "all")` |
| A statement for one year, quarter, TTM or YTD | `get_statements(ticker, statement: "income_statement", period: "FY2025")` |
| How far back does the data go? | `list_periods(ticker)` |
| Segments, products, geography | `get_segments(ticker, breakdown?)` |
| KPIs, non-GAAP, bank or insurance metrics | `get_company_metrics(ticker, kind?)` |
| Margins | `get_margins_and_ratios(ticker)` |
| A company-specific metric | `list_company_figures(ticker, query: "data center")`, then `get_figure` |
| Compare companies | `compare_companies(["NVDA","AMD","AVGO"], "revenue")` |
| Risks, strategy, management's discussion | `get_narrative(ticker, section: "risk factors")` (or `business`, `md&a`, `current quarter`, `legal`, `subsequent events`) |
| What did the company announce? | `get_events(ticker)`, or `section: "earnings"`, `"m&a"`, `"management changes"`, ... |
| Find a topic anywhere in the filings | `search_text(ticker, query)` |
| Which filing did a number come from? | `get_figure` (a `sec_link` on every tagged value), `get_filings(ticker, accession?)` |
| Currency, ADR ratio, splits, fiscal calendar | `get_reporting_conventions(ticker)` |
| Not sure? | `guide()` |

Tickers are case-insensitive, and `BRK.B` and `BRK-B` both resolve.

## How the data is organized

### Records and periods

A **record** is the complete snapshot built when a company filed one 10-Q or 10-K, tagged by fiscal period: `FY27Q2` is the record built from NVIDIA's second-quarter fiscal 2027 10-Q, `FY26` one built from a 10-K. Each record holds several **periods**: up to three fiscal years, the latest quarter and its prior-year comparative, year to date and trailing twelve months. Older records hold older quarters, so a company's history is the union of its records, and every record stays published at a permanent dated URL.

Tools that take `period` search every record automatically. Tools that take `record` read one snapshot, the latest by default.

### The period argument

| You pass | You get |
| --- | --- |
| nothing | every period in the latest record |
| `FY2025`, `FY25`, `fiscal 2025`, `2025` | that fiscal year (the company's own fiscal year, not the calendar year) |
| `Q2 FY2027`, `Q2 2027`, `FY27Q2`, `2027Q2`, `2Q27`, `second quarter 2027` | that quarter |
| `Q2` | the latest second quarter held |
| `latest`, `latest quarter`, `latest annual` | the most recent period of that kind |
| `ttm`, `ytd`, `prior ytd` | trailing twelve months, year to date, the prior year's year to date |
| `annual`, `quarterly`, `all` | every fiscal year, every quarter, or every period in every record |
| `2026-07-26` | the period ending on that date |

A period earlier than anything held is not an error. The answer says the data does not go back that far and lists exactly what is held. A period not yet reported says so and gives the next expected filing.

### Names in the record

Records are shaped to each business, so the same line item has different names: Apple's revenue is `total_net_sales`, JPMorgan's is `total_net_revenue`, Walmart's net income is `net_income_attributable_to_walmart`. Nothing is relabeled to hide that.

- Every value a figure tool returns leads with `name_in_record` (the record's own name), `field` (its path inside the period) and `json_path` (its exact address in `financials.json`, e.g. `annual[0].income_statement.total_net_sales`).
- Any of those names can be passed back to `get_figure` exactly as written, and returns exactly that field. Case, spaces and underscores do not matter: `Data Center` and `revenue_by_market_platform.Data Center` both work.
- A standard figure asked for by its generic words (`revenue`, `net income`, `free cash flow`) resolves the standard way below, each value still under the record's own name. If the record also has other fields of that name (NVIDIA's segment tables each carry a `revenue`), they are listed under `other_fields_with_this_name`, callable by path.
- `list_company_figures` maps each standard figure to the name this company uses, then lists every remaining figure under its own name. Pass `query` to search those names.

### Standard figures

`get_figure` and `compare_companies` know the names each figure goes by across companies and resolve deterministically: first the field the company's own headline uses for it, then a list of known names in order, then a name pattern only when exactly one field matches. Nothing is estimated, derived or summed to fill a gap. Look-alike fields in the same statement come back under `related`, and a company that reports none of the names gets a plain "not reported" with the closest fields it does have.

| Figure | Ask for it as | Read from, for example |
| --- | --- | --- |
| Revenue | `revenue`, `sales` | `revenue`, `revenues`, `total_revenues`, `total_revenue`, +19 more |
| Cost of revenue | `cost of revenue`, `cogs` | `cost_of_revenue`, `cost_of_sales`, `total_cost_of_revenue`, `cost_of_goods_sold`, +10 more |
| Gross profit, gross margin % | `gross profit`, `gross margin` | `gross_profit`, `gross_margin`, `gross_margin_pct`, +3 more |
| Research and development | `r&d` | `research_and_development`, `research_and_development_expenses`, +7 more |
| Selling, general and administrative | `sga` | `selling_general_and_administrative`, `sales_general_and_administrative`, +7 more |
| Total operating expenses | `operating expenses`, `opex` | `total_operating_expenses`, `total_costs_and_expenses`, `total_noninterest_expense`, +11 more |
| Operating income | `operating income`, `ebit` | `operating_income`, `income_from_operations`, `operating_profit`, +4 more |
| Interest expense | `interest expense` | `interest_expense`, `total_interest_expense`, `interest_expense_net`, `interest_and_debt_expense` |
| Income before income taxes | `pretax income` | `income_before_income_taxes`, `earnings_before_income_taxes`, +23 more |
| Income tax, effective tax rate | `income tax