asian-etf-mcp

An MCP server exposing the Asian ETF Tracker data (5 markets: HK / A-Share / Taiwan / South Korea / US) as tools an LLM agent (or Claude Code/Desktop) can call.

This is the first of several per-project MCP servers for the IvyTrader platform. It establishes the shared interface convention the other MCPs (rays, ivytrader) follow.

Architecture (two layers)

server.py        ← the "menu": thin MCP wrapper, no data logic
   │ calls
data_access.py   ← the "kitchen": Streamlit-free, reads CSV/JSON, computes returns
   │ reads (read-only)
Asian_ETF_Tracker/new/{data,data_ashare,...}/{industry}/{code}.csv

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

Related MCP server: GroundAPI

Tools (the convention)

Conventions (all MCPs in this project follow these):

• names: get_xxx_yyy (snake_case)

• params: market ('hk'/'cn'/'tw'/'sk'/'us' or full name), code, start/end (ISO), days

• every return is {"data": ..., "source": {"project", "files", "as_of"}} — numbers are computed in code, and each result carries its source files for citation.

Setup

python3.13 -m venv .venv          # needs Python 3.10+
./.venv/bin/pip install -r requirements.txt

Data freshness (where the CSVs come from)

The live data lives on the deployment server (138.199.208.197:/opt/etf-tracker), where the etf-collector timer refreshes the CSVs every weekday. To serve that fresh data, sync_data.sh SSH-pulls the server's configs + CSVs into ./server_mirror/, which is the default data root.

./sync_data.sh                    # pull latest from the server into server_mirror/

Schedule it so the MCP stays fresh (every weekday 09:00):

0 9 * * 1-5  /Users/aa/Desktop/new/asian-etf-mcp/sync_data.sh

Every tool result carries source.as_of so the agent always knows how fresh the data is. Override the data root with ASIAN_ETF_ROOT=/some/other/path if needed.

Test the data layer (no MCP needed)

./.venv/bin/python test_data_access.py

Register with Claude Code

claude mcp add asian-etf -- /Users/aa/Desktop/new/asian-etf-mcp/.venv/bin/python \
  /Users/aa/Desktop/new/asian-etf-mcp/src/server.py

Then ask Claude things like "用 asian-etf 看看港股哪个行业动量最强" and it will call get_industry_momentum.