rays-mcp

An MCP server exposing global market breadth, volume, RSI, volatility and sentiment for 12 major equity indices (US + Asia: S&P 500, Nasdaq 100, SOX, Russell 2000, Hang Seng, CSI 300/1000, ChiNext, Nikkei 225, Topix, Taiwan, KOSPI 200).

Companion to asian-etf-mcp; same two-layer design (data layer + thin FastMCP wrapper), same cache + refresh-on-use model.

Tools

tool	returns
list_indices	the 12 indices + tickers (call first)
get_breadth	% of constituents above 50/200-day MA, % above/below both, advancers/decliners
get_volume	real trading volume (constituent-aggregated) vs 20-day average + deviation
get_rsi	RSI(14) per index + overbought/oversold signal
get_volatility_sentiment	VIX (+ >30 alert), GLD/VIX momentum, AAII bull/neutral/bear survey

Every result carries source (with as_of + computed_at).

How it works

src/server.py        FastMCP wrapper (5 tools)
src/data_access.py   reads cache.json; refresh-on-use keeps it current
build_cache.py       assembles cache.json from 3 sources:
configs/indices.json index definitions (committed)

cache.json is assembled from:

1. breadth_cache.json — breadth / advance-decline / real volume. The heavy constituent aggregation (Topix ≈ 1,574 stocks!) is precomputed daily on the rays server, so the MCP reads it rather than recomputing.
2. yfinance — RSI(14, Wilder), VIX, GLD/VIX momentum (computed live).
3. aaii_sentiment.xls — the weekly AAII investor sentiment survey.

When a tool is called and the cache is behind the latest trading day, the server rebuilds it first (sync_data.sh + build_cache.py) — no cron needed.

Quick start

python3.10+ -m venv .venv
./.venv/bin/pip install -r requirements.txt
./.venv/bin/python build_cache.py        # assemble the cache

Use with Claude Code

claude mcp add rays -- /abs/path/.venv/bin/python /abs/path/src/server.py

Then ask, e.g. “use rays — which markets have the broadest participation and is the VIX elevated?”

Data access note

The breadth/volume layer is computed on the maintainer's rays server (constituent aggregation across thousands of stocks is too heavy to recompute on demand). sync_data.sh pulls that precomputed file via SSH. The RSI / VIX / GLD layer is fetched from public Yahoo Finance, so it works anywhere; AAII comes from the synced weekly file. To run fully standalone, supply a data/breadth_cache.json produced by the rays-dashboard pipeline.

Configuration

env var	default	meaning
RAYS_CONFIG	./configs/indices.json	index definitions (committed)
RAYS_DATA_DIR	./data	synced/generated data (gitignored)
RAYS_SERVER	root@91.98.37.33	rays server for sync_data.sh