asian-etf-mcp

An MCP server that exposes thematic ETF data across 5 Asian markets + the US (Hong Kong, China A-Share, Taiwan, South Korea, US) as tools an LLM agent — or Claude Code / Claude Desktop — can call.

It fetches public OHLCV data from Yahoo Finance, computes industry returns / momentum / rankings, and serves them through a small set of well-described tools. Every result carries its source files and as_of date, so answers built on it are auditable.

Tools

tool	args	returns
list_markets	—	every market → industries → ETFs (call first to discover)
get_etf_performance	market, industry, start?, end?	each ETF's total return vs the benchmark
get_industry_momentum	market, end_date?	per-industry 5d / 21d / 63d / YTD return, absolute + relative
get_industry_ranking	market, start?, end?	industries ranked by return
get_etf_ohlcv	code, market, start?, end?	raw daily OHLCV bars

market accepts hk / cn / tw / sk / us (or full names). Dates are ISO strings like 2025-06-01.

Quick start

git clone https://github.com/ivyyy0601/etf-mcp.git
cd etf-mcp                       # (or the asian-etf-mcp directory)
python3.10+ -m venv .venv
./.venv/bin/pip install -r requirements.txt

# Build the data cache once (fetches ~55 symbols from Yahoo Finance, ~2-3 min)
./.venv/bin/python build_cache.py

That's it — the server is self-contained. The market/industry/ETF definitions ship in configs/, and the data comes from public Yahoo Finance, so you don't need any account, API key, or access to anyone's server.

Use with Claude Code

claude mcp add asian-etf -- /abs/path/to/.venv/bin/python /abs/path/to/src/server.py

Then ask, e.g. “use asian-etf to show which US sector has the strongest momentum.”

How it works

Two layers, kept separate on purpose:

src/server.py        the "menu": thin FastMCP wrapper, one @mcp.tool() per function
   │ calls
src/data_access.py   the "kitchen": reads CSVs, computes returns/momentum/rankings

data_access.py has no MCP dependency — it returns plain Python objects and can be imported by anything (tests, a notebook, a LangGraph agent). server.py only adds the protocol + tool descriptions.

Caching (fast reads). build_cache.py precomputes every standard view into cache.json once. Default-parameter tool calls are served from that cache (instant); only custom date ranges are computed on the fly.

Refresh-on-use (always current, zero babysitting). When a tool is called and the cache is older than the latest trading day, the server rebuilds it first (fetches the latest data), then answers. So you never have to run a cron or open anything — it self-maintains.

Configuration

env var	default	meaning
ASIAN_ETF_ROOT	./data	where OHLCV CSVs are stored (generated)
ASIAN_ETF_CONFIG_DIR	./configs	market/industry/ETF definitions (shipped)

To add a market or ETF, edit the JSON files in configs/ — no code changes.

Keeping it fresh

• Anyone: nothing to do — refresh-on-use fetches the latest from Yahoo Finance when needed. Or run python build_cache.py whenever you want.
• Maintainer fast-path (optional): if you run the companion data collector on a server, sync_data.sh can pull its daily CSVs and build_cache.py --no-live recomputes from them in seconds. Requires SSH access to that server; everyone else simply uses the live Yahoo Finance path.

Project layout

src/server.py        MCP server (5 tools)
src/data_access.py   Streamlit-free data + cache layer
build_cache.py       refresh job: fetch + precompute → cache.json
configs/             market definitions (committed)
sync_data.sh         maintainer fast-path (optional)
test_data_access.py  smoke test for the data layer (no MCP needed)