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 for why that matters).

Install

Requires Node.js ≥ 18.

Claude Code (CLI)

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):

{
  "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 for the reverse-engineered API contract.

Development

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:

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