# tickertape-mcp

An MCP server for **screening and analyzing US stocks and ETFs** using Tickertape's
screener data, usable from any MCP client. Ask in plain language — "profitable US
semiconductor stocks under 20× P/E with ROE above 20%" — and get a ranked, filterable
table back.

> **Disclaimer.** This is an **unofficial** project. It is not affiliated with, endorsed
> by, or supported by Tickertape or Smallcase. It calls an **undocumented** public API
> that may change or break at any time. Data is provided "as is", may be delayed or
> wrong, and is **not investment advice**. Only the **US** market is supported. Use at
> your own risk and review Tickertape's terms of service before use.

## Features

- **`screen_stocks`** — filter US stocks by any of 70+ metrics (valuation, growth,
  profitability, dividends, technicals, ownership, analyst ratings), plus sector /
  industry, with sorting and pagination.
- **`screen_etfs`** — screen ETFs by AUM, expense ratio, returns, yield, and fund
  category.
- **`list_filters`** — discover the available metrics, their units, value ranges, and the
  allowed sector/industry values.
- **`search_stocks`** — look up a ticker or company name.
- **`get_stock_details`** — a full metric snapshot for one stock or ETF, grouped by
  category, with a link to its Tickertape page.

It validates every metric name and value against the live filter catalog, so a typo gets
a helpful "did you mean" instead of silently wrong results (see
[docs/api-notes.md](docs/api-notes.md) for why that matters).

## Install

Requires Node.js ≥ 18.

### Claude Code (CLI)

```bash
claude mcp add tickertape -- npx -y tickertape-mcp
```

### Claude Desktop / Cursor

Add to your MCP config (`claude_desktop_config.json`, or Cursor's `mcp.json`):

```json
{
  "mcpServers": {
    "tickertape": {
      "command": "npx",
      "args": ["-y", "tickertape-mcp"]
    }
  }
}
```

Then restart the client. No API keys or account are needed.

## Example prompts

- "Screen US stocks: market cap over $10B, P/E under 25, ROE above 15%, in Technology.
  Sort by dividend yield."
- "Find low-cost S&P 500 ETFs — expense ratio under 0.05%, sorted by AUM."
- "What are NVDA's valuation and profitability metrics?"
- "Which large-cap healthcare stocks are trading more than 30% below their 52-week high?"

## Tools reference

| Tool | Key parameters |
| --- | --- |
| `list_filters` | `category?`, `search?` |
| `screen_stocks` | `filters: [{metric, min?, max?}]`, `sectors?`, `industries?`, `sort_by`, `sort_order`, `columns?`, `limit`, `offset` |
| `screen_etfs` | `filters`, `categories?`, `sort_by`, `sort_order`, `columns?`, `limit`, `offset` |
| `search_stocks` | `query`, `asset_type` (`stock`\|`etf`), `limit` |
| `get_stock_details` | `ticker`, `asset_type`, `metrics?` |

Metric names accept either a friendly **alias** (`peRatioTtm`, `marketCap`,
`returnOnEquity`, `dividendYield`, `debtToEquity`, `expenseRatio`, `aum`) or the raw
Tickertape label. Call `list_filters` to see them all. **Premium** metrics (e.g. forward
P/E, analyst estimates) can be shown as columns but not used to filter or sort — that
requires a Tickertape subscription.

## How it works

- On first use it fetches Tickertape's filter catalog (cached in memory) to build the
  metric list and aliases.
- `search_stocks` / `get_stock_details` build a local index of the full universe the
  first time they run (a few seconds), cached on disk under
  `~/.cache/tickertape-mcp/` (override with `TICKERTAPE_MCP_CACHE_DIR`) for 24 hours.
- All output is compact markdown to keep token usage low.

See [docs/api-notes.md](docs/api-notes.md) for the reverse-engineered API contract.

## Development

```bash
npm install
npm run typecheck     # tsc --noEmit
npm test              # vitest, uses fixtures (no network)
npm run build         # bundle to dist/ with tsup
npm run smoke         # live end-to-end checks against the real API (not in CI)
```

Inspect the server interactively:

```bash
npm run build
npx @modelcontextprotocol/inspector node dist/index.js
```

### Project layout

```
src/
  index.ts     entry — starts the stdio MCP server
  server.ts    tool registration and wiring
  api.ts       HTTP client for the Tickertape API
  catalog.ts   filter catalog: fetch, aliases, name/value resolution
  match.ts     builds a query body from tool input (the silent-failure guard)
  universe.ts  local ticker/name index with disk cache
  format.ts    markdown renderers
```

### Publishing checklist

1. `npm run typecheck && npm test && npm run build`
2. `npm pack --dry-run` — confirm the tarball contains only `dist/`, `README.md`,
   `LICENSE`.
3. Test the bin: `npx ./tickertape-mcp-<version>.tgz`.
4. `npm publish --access public` (optionally `--provenance` from CI).

## License

[MIT](LICENSE)