io.github.nirajagarwal/stox-mcp

Official6 tools

by nirajagarwal

Percentile fingerprints, curated peers, theme clusters & market-stress context for US stocks.

stox-mcp (io.github.nirajagarwal/stox-mcp)

stox-mcp is an MCP server that provides a judgment/context layer for US stocks. It works over the stox.market metric layer, supporting “percentile fingerprints, curated peers, theme clusters & market-stress context” rather than raw financial data.

🛠️ Key Features

Percentile fingerprints
Curated peers
Theme clusters
Market-stress context
6 tools (toolCount: 6)
Topic: stocks

🚀 Use Cases

Evaluating whether a stock-related number is “good” using context (“context, not data”).
Adding market-stress and peer/thematic context to AI workflows that already have raw bars and statements.

⚡ Developer Benefits

Access via a live HTTP endpoint: https://mcp.stox.market/mcp (streamable HTTP)
Tooling is exposed through the MCP interface
Documentation available at: https://stox.market/mcp

Topics

stocks

Captured live from the server via tools/list.

fingerprint

The character of one stock in ~550 tokens: 16 percentile scores (vs the S&P 500 cohort) across four panels — Market Beat, Trend Persistence, Business Growth, Pressure (money flow) — plus the composite P3 score (the validated 3-factor form), curated competitive peers (not GICS), a one-line character read, and the price line. Use for 'is this number good?' and quick company character.

Parameters2

ticker	string	required	US ticker, e.g. NVDA
as_of	string	optional	RESERVED (phase 2): YYYY-MM-DD point-in-time snapshot; currently only the live snapshot is served

Raw schema

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "description": "US ticker, e.g. NVDA"
    },
    "as_of": {
      "description": "RESERVED (phase 2): YYYY-MM-DD point-in-time snapshot; currently only the live snapshot is served",
      "type": "string"
    }
  },
  "required": [
    "ticker"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

compare

The 16 percentile scores + P3 + 1Y price change for 2-5 tickers as one compact matrix (rows = metrics, columns = tickers). Use when weighing names against each other; percentiles make the comparison fair across sectors and sizes.

Parameters1

tickers

array

required

2-5 US tickers

Raw schema

{
  "type": "object",
  "properties": {
    "tickers": {
      "minItems": 2,
      "maxItems": 5,
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "2-5 US tickers"
    }
  },
  "required": [
    "tickers"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

peers

The stock's TRUE competitive cluster — LLM-curated from segment overlap (who it actually competes with for revenue), not GICS classification. Costco's peers are WMT/TGT/KR, not 'Discount Stores'. Each peer carries its P3 score. Honest empty list for monopolies/private-rival cases.

Parameters1

ticker

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string"
    }
  },
  "required": [
    "ticker"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

theme_cluster

The statistical theme a stock actually trades with: clusters built from years of price co-movement (market-removed residuals → random-matrix cleaning → Ward linkage), not sector labels. Returns the cluster's name, description, cohesion, sector mix and up to 20 member tickers. Different question from `peers` (business competition) — this is who it MOVES with.

Parameters1

ticker

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string"
    }
  },
  "required": [
    "ticker"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

screen

Screen the S&P 500 + NDX universe on ANY of the 16 percentile scores, with minimum AND maximum bounds, optionally within one GICS sector, sorted by the validated P3 composite or by any single metric. Metric keys: marketBeat1Y/1M/1W/1D (price vs SPY), rankPersistence52W/26W/13W + trendPersistence (rank stability), businessBeat + revGrowthYoy + marginGrowthYoy + fcfGrowthYoy (business growth), accumDistFlow/30/5/2 (money flow 60/30/5/2-day). Examples: momentum — {sort_by:'marketBeat1M', filters:[{metric:'businessBeat', min:70}]}; fallen leaders — {filters:[{metric:'rankPersistence52W', min:80},{metric:'marketBeat1Y', max:40}]}. Legacy min_perform/min_persist/min_profit/min_pressure still work (the four headline scores).

Parameters8

filters	array	optional	bounds on any metrics; entries AND together
sort_by	string	optional	'p3' (default) or any metric key; descending
min_perform	number	optional
min_persist	number	optional
min_profit	number	optional
min_pressure	number	optional
sector	string	optional	GICS sector filter, e.g. 'Energy'
n	number	optional	max results (default 12)

Raw schema

{
  "type": "object",
  "properties": {
    "filters": {
      "description": "bounds on any metrics; entries AND together",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "metric": {
            "type": "string",
            "description": "one of the 16 metric keys"
          },
          "min": {
            "type": "number",
            "minimum": 0,
            "maximum": 100
          },
          "max": {
            "type": "number",
            "minimum": 0,
            "maximum": 100
          }
        },
        "required": [
          "metric"
        ]
      }
    },
    "sort_by": {
      "description": "'p3' (default) or any metric key; descending",
      "type": "string"
    },
    "min_perform": {
      "type": "number",
      "minimum": 0,
      "maximum": 100
    },
    "min_persist": {
      "type": "number",
      "minimum": 0,
      "maximum": 100
    },
    "min_profit": {
      "type": "number",
      "minimum": 0,
      "maximum": 100
    },
    "min_pressure": {
      "type": "number",
      "minimum": 0,
      "maximum": 100
    },
    "sector": {
      "description": "GICS sector filter, e.g. 'Energy'",
      "type": "string"
    },
    "n": {
      "description": "max results (default 12)",
      "type": "number",
      "minimum": 1,
      "maximum": 25
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

market_regime

Where market stress sits right now: the dashboard's 8-indicator stance, each indicator's traffic-light band, the VIX 5-year percentile (the ONE input validated as predicting forward risk — blended composites tested worse), and the S2 stress-confirmation badge (SPY below its 40-week average AND VIX above its 80th percentile of the trailing year). Descriptive context, not a market call.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

README.md2 KBView on GitHub

stox-mcp

Give your AI the numbers that matter. An MCP server over the stox.market metric layer — context, not data: every finance feed hands a model raw bars and statements, and the model still can't answer "is this number good?". This server ships the judgment layer instead.

Live endpoint: https://mcp.stox.market/mcp (streamable HTTP) · Demo & docs: stox.market/mcp

bash

claude mcp add --transport http stox https://mcp.stox.market/mcp

Tools

tool	what it answers
`fingerprint`	The character of one stock: 16 percentile scores vs the S&P 500 cohort across four panels (Market Beat, Trend Persistence, Business Growth, Pressure), the P3 composite, curated peers, a one-line read. ~550 tokens.
`compare`	The 16-score matrix for 2–5 tickers, side by side.
`peers`	TRUE competitive peers — curated from segment overlap, not GICS (Costco → WMT/TGT/KR, not "Discount Stores").
`theme_cluster`	Who a stock moves with: co-movement clusters from price behavior (market-removed residuals → random-matrix cleaning → Ward linkage).
`screen`	Min/max bounds on any of the 16 metrics — momentum and fallen-leader queries in one call — optionally per sector, sorted by the P3 composite or any single metric.
`market_regime`	Market-stress stance, per-indicator bands, the VIX 5-yr percentile (the one input validated as predicting forward risk), and the S2 stress-confirmation badge.

Design

Token economy — compact JSON, score + band + a one-line read; a fingerprint is ~550 tokens where a statements dump is 20,000.
Percentiles, not raw numbers — every score is a cross-sectional rank against the real cohort (100 = best), so "is it good?" is answered by construction.
Provenance — snapshot dates on scores, links back to the full picture.
Informational only — descriptive statistics; never investment advice, no buy/sell recommendations. Derived metrics only; this is not a market-data feed.

The human-readable twin

The same metric layer renders as editorial leaderboards at stox.market/lists — 31 boards plus sector slices and frozen earnings-season editions, refreshed on automated weekly lanes. A board is where a name catches your eye; fingerprint is how your agent vets it in one call.

Universe: S&P 500 + NASDAQ-100 + curated ETFs. Coverage and metric definitions: stox.market.

Install

Tools (6)

fingerprintcomparepeerstheme_clusterscreenmarket_regime

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://mcp.stox.market/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "stox-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.stox.market/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

stox-mcp (io.github.nirajagarwal/stox-mcp)

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

Topics

fingerprint

compare

peers

theme_cluster

screen

market_regime

stox-mcp

Tools

Design

The human-readable twin

Install

Remote endpoint

Related servers