# equity-figures-mcp

An MCP server that serves company financial figures as each issuer reported them. Every reported figure has its
source: the document URL, its SHA-256 hash, a locator inside it, the document date, the retrieval date and, for an
EDGAR filing, the SEC accession number. Missing figures stay gaps with their reason; the server fills none.

The data lives in a separate repository, [equity-figures-data](https://github.com/ngkawaix/equity-figures-data), in
two tiers. The server stores no theses or opinions.

- **Curated** (AAPL, AMZN, AVGO, GOOGL, META, MSFT, NVDA): about 25 quarters of figures reviewed against the issuer's
  releases, filings and calls, with segment and non-GAAP lines and computed lens series.
- **XBRL** (25 companies in the pilot, the seven included): every consolidated fact each company tagged in its 10-Q
  and 10-K filings since 2020, as first reported, with later filings' figures for the same period listed as revisions.
  A fourth quarter's three-month flow is usually a gap, because a 10-K reports the year; the `[fy]` series hold the
  year.

A ticker in both tiers defaults to curated; every tool takes `tier` to choose.

Not investment advice. The figures are extracted by software and reviewed, and may still contain errors; check the source document before relying on one.

## Tools

| Tool | What it returns |
|---|---|
| `list_companies` | Tickers, names, tier, publication date and the quarters held |
| `list_metrics` | A ticker's series: id, label, unit, reported or computed, latest value |
| `get_series` | One series by quarter, with the source of every reported point |
| `check_condition` | Your measure and threshold evaluated at every quarter: holding, broken or not established |

Quarters are fiscal quarters in each company's own calendar, labelled like `FY2026Q4`. Series ids starting `cell.`
are reported figures; the others are computed lens series that name the figures they use.

`check_condition` takes a measure such as `{"name": "growth", "series": "cell.revenue", "quarters": 4}` and a
condition such as `">= 10"`. The measures are `level`, `change`, `growth`, `vs_mean`, `spread`, `ttm_sum` and
`ttm_ratio`.

## Install

Claude Code:

```bash
claude mcp add equity-figures -- uvx --from git+https://github.com/ngkawaix/equity-figures-mcp equity-figures-mcp
```

Claude Desktop, in `claude_desktop_config.json`:

```json
{"mcpServers": {"equity-figures": {"command": "uvx",
  "args": ["--from", "git+https://github.com/ngkawaix/equity-figures-mcp", "equity-figures-mcp"]}}}
```

The first start clones and builds the package, which can exceed a client's 30-second connection timeout. If it does,
run `uvx --from git+https://github.com/ngkawaix/equity-figures-mcp equity-figures-mcp` once in a terminal (stop it
with Ctrl+C), then reconnect.

Set `EQUITY_FIGURES_DATA` to a local folder or another base URL to read a different copy of the dataset.

## Tests

```bash
python -m unittest discover -s tests
```