krx-etf-mcp

Find Korean ETFs by what they actually are — and rank them by what they actually did.

An MCP server that puts the Korean ETF market (about 1,160 listings) in front of an AI assistant. Lookup comes first — find a fund by name, issuer, underlying index or category, and read its full detail including the NAV premium. Then rank, compare, and chart.

🇰🇷 한국어 README

Data source: 공공데이터포털 (data.go.kr), service 금융위원회_증권상품시세정보 (GetSecuritiesProductInfoService). Prices originate from the Korea Exchange (KRX). This project is independent and not affiliated with either organisation.

Scope: ETF only. The same upstream service also carries ETN and ELW. They are deliberately out of scope — see Why ETF only.

Table of contents

• What it's for

• The problem this solves

• What the raw API gives you

• Install

• Tools

• Usage examples

• Classification: how it works and when it lies

• Three things to know before trusting a number

• API traps encoded in this server

• Development

• Limitations

• FAQ

Related MCP server: kookmin-stock

What it's for

In priority order:

1. Finding an ETF. By name, by issuer, by underlying index, by category — and reading its full detail once found. This is the daily use.

2. Ranking. Which of these did best over a period.

3. Detail and comparison. Full quote fields, price history, head-to-head.

The sections below are ordered the same way.

The problem this solves

The lookup problem and the ranking problem have the same root cause, so it's worth seeing it through the question that started this project:

"Of the bond-mixed ETFs, which ten rose the most over the last three months?"

That sounds like a lookup. It isn't. Answering it correctly requires six separate things, and the public API provides none of them:

1. Find today's data. Ask for today and you get totalCount: 0 — the portal publishes with a lag. You have to walk backwards to find a day that has rows.

2. Identify bond-mixed ETFs. There is no asset-class field. None. The only signal is the product name.

3. Fetch the whole universe twice. ~1,160 rows per day, paginated, for both ends of the period.

4. Join the two days by ticker and compute the change.

5. Handle the ones that don't join. Nine of the thirty bond-mixed ETFs listed during the period. Drop them silently and your ranking is quietly biased toward survivors.

6. Say what the number means. It is a price return. Distributions are excluded — which matters a great deal for exactly this category.

An assistant asked to do that on the fly will write six pieces of throwaway code and get at least one of them wrong, differently each time. The arithmetic belongs in tested code; the judgement belongs to you.

By the way, the honest answer to the original question was: only five of them rose at all. A naive "top 10" quietly lists five losers as winners. This server reports positive_count alongside the ranking so that fact is visible rather than buried.

What the raw API gives you

Install

Requires Python 3.10+ and a free data.go.kr service key.

1. Get a service key

1. Sign up at data.go.kr (Korean phone/ID not required for the basic tier).

2. Go to 금융위원회_증권상품시세정보 and click 활용신청 (request access). Approval for the development tier is immediate.

3. Copy your key from 마이페이지 → 인증키.

The portal shows the key in two forms, Encoding and Decoding. Either works — this server detects which one you pasted and normalises it. (Getting this wrong is the single most common cause of NO_MANDATORY_REQUEST_PARAMETERS_ERROR.)

2. Register the server with your MCP client

Claude Desktop (claude_desktop_config.json) or Claude Code (.mcp.json):

{
  "mcpServers": {
    "krx-etf": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/dongkyucho17/krx-etf-mcp", "krx-etf-mcp"],
      "env": { "DATA_GO_KR_API_KEY": "paste-your-key-here" }
    }
  }
}

Cursor / Cline / Zed — same shape, in that client's MCP config file.

Any agent framework that speaks stdio MCP:

DATA_GO_KR_API_KEY=... uvx --from git+https://github.com/dongkyucho17/krx-etf-mcp krx-etf-mcp

From a local checkout:

git clone https://github.com/dongkyucho17/krx-etf-mcp && cd krx-etf-mcp
cp .env.example .env          # paste your key into .env
uv run krx-etf-mcp

The key is read from DATA_GO_KR_API_KEY, or KRX_ETF_API_KEY if you prefer to scope it. It is never written to disk, never logged, and never appears in a tool response — see Why the key needs care.

3. Check it works

Ask your assistant: "What's the latest KRX ETF trading day?" You should get a resolved date and a lag count.

Tools

Eleven tools, grouped by what you're doing.

Finding an ETF — the primary use

Performance

Housekeeping

Every tool returns {"ok": true, ...} or {"ok": false, "error": ..., "message": ...}. Nothing raises across the MCP boundary, so a bad date or an expired key produces a readable answer rather than a dead tool.

Usage examples

All output below is real, captured from live responses.

Look up one ETF by name

You rarely know the six-digit code. get_etf_quote takes a code, an ISIN or a name.

get_etf_quote(code_or_name="KODEX 200")

{
  "ok": true,
  "base_date": "20260812",
  "quote": {
    "code": "069500", "isin": "KR7069500007", "name": "KODEX 200", "issuer": "KODEX",
    "close": 103250.0, "change": 1000.0, "change_pct": 1.02,
    "open": 97570.0, "high": 100350.0, "low": 96650.0,       // OHLC
    "volume": 15084783.0, "trade_value": 1391450049502.0,
    "market_cap": 24119200000000.0,
    "nav": 103464.35, "nav_premium_pct": -0.207,             // ← computed here, not in the feed
    "net_asset_total": 23178762287104.0, "listed_shares": 231850000.0,
    "index_name": "코스피 200", "index_close": 987.4,
    "asset_class": "주식", "region": "국내", "strategies": []
  }
}

A partial name that matches several products returns candidates instead of guessing:

get_etf_quote(code_or_name="반도체")

{
  "ok": true, "quote": null, "ambiguous": true,
  "message": "59 ETFs match '반도체'. Pick one by code.",
  "candidates": [
    { "code": "396500", "name": "TIGER 반도체TOP10" },
    { "code": "091160", "name": "KODEX 반도체" }
  ]
}

Browse one issuer's line-up, sorted how you want

search_etf(issuer="TIGER", sort_by="volume", limit=5)

TIGER — 230 listings, sorted volume desc
  252710  TIGER 200선물인버스2X          134,043,548
  0195S0  TIGER SK하이닉스단일종목레버리지     26,619,021
  360750  TIGER 미국S&P500              23,437,266

Former brand names resolve too — issuer="KBSTAR" returns the 143 RISE listings, and ARIRANG / KINDEX / KOSEF behave the same way. Sort on market_cap, volume, trade_value, close, change_pct, nav_premium_pct, name or code, ascending or descending.

"Which KOSPI 200 ETF should I hold?"

25 ETFs track 코스피 200. find_similar_etf puts them side by side on the three things that separate them: size, liquidity, and how far the price sits from NAV.

find_similar_etf(code_or_name="KODEX 200", sort_by="market_cap")

reference: KODEX 200   index: 코스피 200   peers: 25

  name              market cap (억)      volume    nav premium %
  KODEX 200                 241,192  15,084,783          -0.207
  TIGER 200                  99,632   9,257,408          -0.203
  KODEX 레버리지               58,676  20,595,774          -0.612
  RISE 200                   44,367     802,169          -0.205
  ACE 200                    18,277     235,324          -0.132
  PLUS 200                   14,559     288,751          -0.279

Note that leveraged products appear here — they genuinely track the same index. Their strategies field says so, and search_etf(index_name="코스피 200") plus a filter narrows it.

Map the market by underlying index

list_indices(min_etf_count=10)

  25  코스피 200            largest: KODEX 200
  24  S&P 500             largest: TIGER 미국S&P500
  16  NASDAQ 100          largest: TIGER 미국나스닥100
  16  코스피 200 선물지수      largest: KODEX 인버스
  13  코스피                largest: KODEX 코스피
  12  코스닥 150            largest: KODEX 코스닥150
  11  코리아 밸류업 지수       largest: RISE 코리아밸류업
  11  미국달러선물지수         largest: KODEX 미국달러선물인버스2X

Use the exact strings from here with search_etf(index_name=...).

Find the widest NAV premiums and discounts

search_etf(min_volume=10000, sort_by="nav_premium_pct", limit=3)
search_etf(min_volume=10000, sort_by="nav_premium_pct", ascending=True, limit=3)

  +7.785%  RISE 코리아밸류업위클리고정커버드콜
  +6.991%  RISE 미국AI클라우드인프라
  ...
  -2.987%  TIGER 차이나항셍테크레버리지(합성 H)
  -2.841%  KODEX 차이나H레버리지(H)

Rank a category by return

You: "Top 3 bond-mixed ETFs by 3-month return."

rank_etf_return(asset_class="채권혼합", months=3, top=3)

{
  "ok": true,
  "start_date": "20260511",       // both ends resolved to days that have data
  "end_date": "20260811",
  "requested_start": "20260511",
  "candidates": 30,
  "positive_count": 5,            // ← only 5 of 30 actually rose
  "negative_count": 25,
  "ranking": [
    {
      "rank": 1,
      "code": "447660",
      "name": "PLUS 애플채권혼합",
      "start_close": 13495.0,
      "end_close": 13690.0,
      "return_pct": 1.44,
      "market_cap": 22588500000.0,
      "volume": 21545.0,
      "nav": 13689.78,
      "index_name": "FnGuide 애플채권혼합 지수",
      "asset_class": "채권혼합",
      "region": "미국",
      "strategies": []
    },
    { "rank": 2, "code": "0049K0", "name": "ACE 미국배당퀄리티채권혼합50",
      "return_pct": 1.43, "region": "미국", "strategies": ["배당"] },
    { "rank": 3, "code": "447620", "name": "SOL 미국TOP5채권혼합50",
      "return_pct": 0.68, "region": "미국", "strategies": [] }
  ],
  "excluded_count": 9,            // ← reported, not silently dropped
  "excluded": [
    { "code": "0184N0", "name": "PLUS 은채권혼합",
      "reason": "no_data_at_period_start",
      "detail": "Listed after the start date, or not traded that day." }
  ],
  "return_disclaimer": "Price return only: computed from closing prices, distributions excluded. ..."
}

Note what the shape of this answer lets an assistant say: "Five of thirty rose; the top three are all US-underlying; nine were excluded because they listed mid-period." That is a different answer from "here are the top three", and a more honest one.

Find the losers instead

rank_etf_return(asset_class="채권혼합", months=3, top=3, worst=True)

{
  "start_date": "20260511", "end_date": "20260811",
  "ranking": [
    { "rank": 1, "code": "0186S0", "name": "1Q 코스닥150채권혼합50액티브",
      "start_close": 9870.0, "end_close": 8630.0, "return_pct": -12.56,
      "region": "국내", "strategies": ["액티브"] },
    { "rank": 2, "code": "0132K0", "name": "PLUS 테슬라위클리커버드콜채권혼합",
      "start_close": 9165.0, "end_close": 8120.0, "return_pct": -11.4 }
  ]
}

Search by strategy and region

You: "Show me US covered-call ETFs."

search_etf(strategy="커버드콜", region="미국", limit=3)

{
  "ok": true,
  "base_date": "20260811",
  "universe_size": 1163,
  "match_count": 38,
  "results": [
    {
      "code": "486290",
      "isin": "KR7486290000",
      "name": "TIGER 미국나스닥100타겟데일리커버드콜",
      "close": 10965.0,
      "change": -65.0,
      "change_pct": -0.59,
      "volume": 1109611.0,
      "market_cap": 2357475000000.0,
      "nav": 10936.12,
      "index_name": "NASDAQ 100 Daily Covered Call Target Premium 15% 지수(TR)",
      "issuer": "TIGER",
      "nav_premium_pct": 0.264,
      "asset_class": "주식",
      "region": "미국",
      "strategies": ["커버드콜", "데일리"],
      "region_inferred": false,
      "asset_class_inferred": true   // ← no asset keyword fired; equity was assumed
    }
  ]
}

Results default to market-cap order, so the liquid names come first. Filters combine freely:

search_etf(asset_class="채권혼합", region="미국")
search_etf(strategy="레버리지", issuer="KODEX")
search_etf(query="반도체", min_market_cap=1e11, sort_by="change_pct")
search_etf(index_name="S&P 500", sort_by="nav_premium_pct", ascending=True)

Price history for one ETF

get_etf_history(code="069500", months=1)

{
  "ok": true,
  "code": "069500",
  "name": "KODEX 200",
  "start_date": "20260713",
  "end_date": "20260811",
  "trading_days": 21,
  "period_return_pct": -8.78,
  "series": [
    { "base_date": "20260713", "close": 108820.0, "change_pct": -9.77,
      "volume": 28358089.0, "nav": 108583.09, "market_cap": 23793493000000.0 },
    { "base_date": "20260714", "close": 109720.0, "change_pct": 0.83, "volume": 33989327.0 },
    { "base_date": "20260715", "close": 116735.0, "change_pct": 6.39, "volume": 21886708.0 }
  ]
}

Compare specific tickers

You: "KODEX 200 vs TIGER 나스닥100 vs TIGER S&P500, past 6 months."

compare_etf(codes=["069500", "133690", "360750"], months=6)

{
  "start_date": "20260211",
  "end_date": "20260811",
  "comparison": [
    { "rank": 1, "code": "069500", "name": "KODEX 200",
      "start_close": 79115.0, "end_close": 99265.0, "return_pct": 25.47, "region": "국내" },
    { "rank": 2, "code": "133690", "name": "TIGER 미국나스닥100",
      "start_close": 161860.0, "end_close": 185825.0, "return_pct": 14.81, "region": "미국" },
    { "rank": 3, "code": "360750", "name": "TIGER 미국S&P500",
      "start_close": 25015.0, "end_close": 27215.0, "return_pct": 8.79, "region": "미국" }
  ],
  "not_found": []
}

Audit a classification you don't trust

explain_classification(name="SOL 팔란티어커버드콜OTM채권혼합")

{
  "name": "SOL 팔란티어커버드콜OTM채권혼합",
  "asset_class": "채권혼합",
  "region": "미국",
  "strategies": ["커버드콜"],
  "matched_keywords": ["채권혼합", "팔란티어", "커버드콜"],
  "region_inferred": false,
  "asset_class_inferred": false
}

Three keywords fired, and you can see all three. If a verdict looks wrong, this is where you find out why — and it makes a good bug report.

Prompts that work well

Lookup:

• "What is KODEX 200 trading at, and how far is it from NAV?"

• "Show me every TIGER ETF with US exposure, biggest first."

• "Which ETFs track the S&P 500? Sort them by how tightly they hold NAV."

• "I want a KOSPI 200 ETF. Which one is largest and most liquid?"

• "What indices have the most ETFs competing on them?"

Performance:

• "Which US-underlying bond-mixed ETFs beat their domestic equivalents over 6 months?"

• "Find covered-call ETFs with more than 100 billion KRW in market cap, ranked by 3-month return."

• "What were the worst-performing leveraged ETFs last month, and how many were excluded?"

Classification: how it works and when it lies

The upstream service exposes no category field whatsoever. Asset class, region and strategy are therefore derived from the product name.

This works better than it sounds, because Korean ETF names are highly conventional — the issuer prefix, underlying, and strategy are all encoded in the name by convention. It is still a heuristic, and it will be wrong sometimes.

Accepted values (from list_filters):

issuer is the one classification that never guesses. Every listed Korean ETF leads with its brand, so the first token identifies it exactly, for all 1,163 current listings. It is deliberately not mapped to a management-company name: the brand is what the data contains, and a hard-coded company table would rot every time a line is renamed or sold. Renames are handled the other way round — a query for a former brand (KBSTAR, ARIRANG, KINDEX, KOSEF, 히어로즈) resolves to the current one, so older write-ups still work as search terms.

Order matters, deliberately. 채권혼합 (bond-mixed) is checked before 채권 (bond), because "채권혼합" contains "채권" — a naive rule set files every bond-mixed fund as a plain bond fund. There is a regression test pinning exactly this.

Three safeguards against the heuristic quietly misleading you:

1. asset_class_inferred / region_inferred are true when no keyword fired and a default was assumed. A true here means "guessed", not "determined".

2. explain_classification shows every keyword that matched.

3. Each search response repeats classification_note so a reading assistant relays the caveat.

Known blind spots. A bond-mixed fund whose name omits "채권혼합" will be missed. A US-underlying fund named only after an index this server doesn't recognise falls back to 국내. Company names are enumerated, so a newly popular underlying may not be recognised until it's added. Issues with the product name and the verdict you expected are welcome and easy to fix — the rules are plain tuples in categories.py.

Three things to know before trusting a number

1. Returns are price returns. The feed carries closing prices only, so distributions are not reinvested. This understates total return — materially for high-distribution categories such as covered-call and bond-mixed ETFs, which is to say exactly the categories people most often rank. Every return-bearing response repeats this in return_disclaimer.

2. Dates resolve backwards, silently but visibly. The portal publishes with roughly a one-day lag; weekends and holidays add more. Any date you pass is walked back up to 14 days to the newest day with rows. The date actually used is echoed in every response as start_date / end_date / base_date. Never assume the date you asked for is the date you got — read it back.

3. Nothing is dropped silently. ETFs missing a price at either end of a period are returned in excluded with a machine-readable reason, not omitted. This is not politeness: in the founding example, 9 of 39 bond-mixed ETFs had listed mid-period, and dropping them without comment would have biased the ranking toward whatever happened to have survived the whole window.

API traps encoded in this server

These cost real debugging time. They're documented here so you don't repeat them, and encoded in the code so you don't have to.

Why the key needs care

Because the key must live inside the URL (see above), it lands in any HTTP request log. httpx logs every request line at INFO, so a default setup writes your key in plaintext to wherever your agent's stderr goes. This server:

• lowers the httpx and httpcore loggers to WARNING at import,

• redacts the key from every exception message before re-raising (both encoded and decoded forms),

• and uses raise ... from None so the chained traceback, which also carries the URL, is dropped.

If you use another data.go.kr client alongside this one, check its logs. This is easy to get wrong and invisible until you look.

Development

uv sync --extra dev
uv run pytest

Or with no dependencies at all:

PYTHONPATH=src python -m unittest discover -s tests

31 tests, no network and no key required. Fixtures are real product names and real closing prices captured from live responses, so they double as a regression net for the classification rules.

src/krx_etf_mcp/
├── client.py       # HTTP, paging, date resolution, key handling, caching
├── categories.py   # name → asset class / region / strategy
├── dates.py        # YYYYMMDD maths, including the exclusive-endBasDt shift
├── returns.py      # normalisation, filtering, period-return join
└── server.py       # MCP tool definitions

The three modules below server.py have no MCP dependency and can be imported directly if you want the data without an agent.

Contributions are welcome — especially classification rules for products this misfiles.

Limitations

• ETF only. No ETN, ELW, or non-KRX listings.

• Price return only. No distributions, so no total return.

• Name-based classification. Not an official KRX taxonomy.

• Daily closes only. No intraday, no order book, no flows.

• No holdings data. The upstream service carries prices, not constituents.

• Rate limits. 30 TPS upstream; daily call quotas depend on your data.go.kr account tier. Daily snapshots are cached in-process, so a session that ranks several categories over the same period costs one pair of fetches, not one per query.

• History depth is whatever the portal retains; it does not extend to an ETF's full history.

Why ETF only

The same upstream service exposes ETN and ELW, and adding them would be perhaps fifty lines. They are excluded on purpose: their response schemas differ (ETN carries indicative value, ELW carries strike and expiry), the classification rules would not transfer, and a tool named for one job it does well is more useful than one named for three it does adequately. If you want them, open an issue — the case is worth hearing.

FAQ

Is the data real-time? No. Daily closes, published with roughly a one-day lag.

Does it cost anything? No. The data.go.kr development tier is free.

Can I use it without an AI assistant? Yes — import client.py, categories.py and returns.py directly. They are plain Python with no MCP dependency.

Why not use the KRX API directly? KRX's own open API exists but requires separate registration and returns a different shape. This server uses the public-portal relay because the key is easier to get and the data is the same, sourced from KRX.

A classification is wrong. Run explain_classification on the name, then open an issue with the name and the verdict you expected. The rules are plain tuples and easy to correct.

Which mcp SDK versions work? Both 1.x (FastMCP) and 2.x (MCPServer) — the import is version-detecting.

License

MIT — see LICENSE.