# StocksScores

> 0-100 scores for US-listed common stock, from a technical and a fundamental pillar,
> with news sentiment shown beside them. No key and no paid tier: everything below
> answers an anonymous request. The MCP tools are metered tightly, the REST endpoints
> generously — see the limits below.

This file is the plain-text twin of https://app.stocksscores.com/developers, which is a
React app and therefore unreadable to anything that does not run JavaScript. That page
now asks for a StocksScores account; this file does not, and stays the readable copy.

## MCP server

  https://api.stocksscores.com/mcp

Streamable HTTP transport (JSON-RPC 2.0 over POST), no authentication, no session, no
SSE stream. `GET /mcp` answers 405 by design. Tool calls are metered — one a minute and
ten a day per IP; see the limits below before you plan a run.

Claude Code:

  claude mcp add --transport http stocksscores https://api.stocksscores.com/mcp

Claude Desktop, Cursor, or any client with a JSON config:

  {
    "mcpServers": {
      "stocksscores": {
        "type": "http",
        "url": "https://api.stocksscores.com/mcp"
      }
    }
  }

Or speak JSON-RPC to it directly:

  curl -s https://api.stocksscores.com/mcp \
    -H 'Content-Type: application/json' \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
         "params":{"name":"top_scores","arguments":{"limit":5}}}'

### Tools

- `get_stock_analysis(symbol)` — the composite for one symbol with its three pillars,
  the technical score per timeframe, and the current quote. Computed live, cached two
  hours.
- `screen_stocks(minScore?, maxScore?, sector?, limit?)` — filters last night's scored
  universe, best first. `limit` defaults to 25, caps at 200.
- `top_scores(limit?)` — the highest scoring symbols right now. `limit` defaults to 10.

## REST API

Base: https://api.stocksscores.com

- `GET /api/analysis/scores?symbol=AAPL` — the composite, the three pillars, the
  technical score per timeframe, the quote. 13-20 KB.
- `GET /api/analysis/fundamental?symbol=AAPL` — valuation, growth, profitability,
  ownership, analyst coverage, the statements themselves. 230-400 KB.
- `GET /api/analysis/news?symbol=AAPL` — news sentiment, earnings-call
  transcripts, the headline feed, the SEC filing list. 90-250 KB.
- `GET /api/analysis/technical?symbol=AAPL&interval=1d` — price series and indicators.
  `interval` is one or more of 5m, 15m, 30m, 1h, 1d, 1wk, 1mo, 3mo, comma-separated;
  anything else is a 400. `series` is symbol | spy | both (default). `fields` is
  `ohlcv` for bars only, or a comma-separated list of series names (`sma10,rsi14`);
  omitted, the interval comes whole. 30-400 KB per interval.
- `GET /api/analysis/all` — the screener feed: last night's score for every covered
  symbol, one row each, with price, sector and the three pillars. Top scores is this
  list sorted by score; there is no separate endpoint for it. ~36 MB, 5.6 MB gzipped.
- `GET /api/analysis/universe` — the same symbols without the sub-scores: symbol, name,
  sector, industry, market cap, price, the composite and the three pillars. ~0.6 MB.
- `GET /api/analysis/history?symbol=AAPL&days=90` — that symbol's latest stored row (the
  `/all` shape) plus its daily composite and pillar totals, oldest first, and the preset
  weights (a scorer with weight 0 is shown but not counted). `days` caps at 365; history
  starts 2026-07-15. 404 when the symbol has no score in the last two days.

## Reading the numbers

Every score is 0-100 and higher is better, including the ones built from metrics where
low is good — a cheap P/E scores high. The composite is the technical and fundamental
pillars at equal weight; the news pillar is returned but not counted. A pillar with no
data is `null`, not zero, and drops out, so a composite can rest on technicals alone —
check the pillars before comparing two composites.

## Coverage

US-listed common stock above $1 and $25M of market cap. Indices, ETFs, funds, OTC and
foreign listings answer 422 with the reason. Baby bonds and preferreds are excluded by
name where Yahoo types them as equity, which is most but not all of them.

## Caching, limits, terms

- Scores are recomputed at most every two hours per symbol, served
  `public, max-age=60, s-maxage=300`. The universe feed is written by a nightly batch
  that starts at 21:30 UTC and takes about four hours.
- REST: 1,000 requests per 10 minutes per IP. Responses carry `RateLimit-Remaining` and
  `RateLimit-Reset`; over the line is a 429.
- MCP `tools/call`: one a minute and ten a day per IP, counted per minute first. The
  handshake — `initialize`, `notifications/initialized`, `tools/list` — is not counted,
  so connecting and listing the tools costs nothing. Budget for it: one question can
  cost several calls, and three symbols compared is three of the ten.
- A throttled tool call is not a 429. It answers 200 with an ordinary tool result
  carrying `isError` and a support address, so the model reads it and can pass it on
  instead of seeing a broken transport. Write to support@stocksscores.com if ten a day
  is not enough.
- CORS is allowed for this site's own origins. Call it from a server, a script or an
  agent rather than from a third-party browser page.
- Scores are information, not investment advice. Attribution appreciated, not enforced.