Krx Etf

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

---

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

What you want to ask	What getETFPriceInfo returns	What this server does
"Today's prices"	totalCount: 0 — data lands a day late	Resolves backwards to the last day with rows, and tells you which day it used
"Bond-mixed ETFs"	No category field at all	Infers asset class, region and strategy from product names, with an audit trail
"Top 10 over 3 months"	No return calculation, no ranking	Joins two daily snapshots and ranks, with filters
"The whole ETF universe"	~1,160 rows across paged requests	Pages and caches per day, in process
"Was anything skipped?"	Silence	Returns an excluded list with a reason for every omission
"Is this total return?"	Nothing	Says price return only on every return-bearing response
"How far is it from NAV?"	Ships clpr and nav, leaves you the division	nav_premium_pct on every record
"Who issues it?"	Nothing — it's in the name, unparsed	issuer field and filter
"What else tracks this index?"	Nothing	find_similar_etf groups by underlying index

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

Tool	Purpose
search_etf	Find ETFs by name, issuer, index and/or classification. Sortable
get_etf_quote	Full detail for one ETF, by code, ISIN or name
find_similar_etf	Every ETF tracking the same underlying index
list_indices	Which underlying indices exist, and how many ETFs track each
list_filters	The accepted filter and sort values
explain_classification	Which keywords drove a classification verdict

Performance

Tool	Purpose
rank_etf_return	Rank by price return over a period, within a filter
compare_etf	Compare specific tickers over one shared period
get_etf_history	Daily closing-price series for one ticker

Housekeeping

Tool	Purpose
latest_trading_day	Resolve the newest date that actually has data
server_info	Version, data source, and limitations

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):

Dimension	Values	Rule
asset_class	채권혼합, 채권, 멀티에셋, 부동산, 원자재, 통화, 주식	First match wins; 주식 is the default
region	미국, 중국, 일본, 인도, 베트남, 유럽, 신흥국, 글로벌, 국내	First match wins; 국내 is the default
strategy	커버드콜, 레버리지, 인버스, 액티브, 배당, 환헤지, 위클리, 데일리, 월배당, TR	Additive — an ETF can carry several
issuer	KODEX, TIGER, RISE, ACE, PLUS, SOL, KIWOOM, HANARO, 1Q, KoAct, TIME, WON, …	Not a heuristic — see below

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.

Trap	What happens	Where it's handled
endBasDt is exclusive	The spec reads "기준일자가 검색값보다 작은" — strictly less than — while beginBasDt is inclusive. Passing your end date verbatim silently drops the most recent day	dates.next_day
Service key must be spliced into the URL pre-encoded	Letting an HTTP library encode it via params= yields NO_MANDATORY_REQUEST_PARAMETERS_ERROR	client._build_url
Encoding vs decoding key	The portal issues both; double-encoding the encoded one fails	client._normalise_key
resultType=json is required	The XML branch is less consistent under the same parameters	client._call
Errors arrive as XML even when JSON was requested	Auth and quota failures return an XML envelope, so a naive json.loads throws something unhelpful	client._parse
Today is usually empty	totalCount: 0 is normal, not an error	client.resolve_trading_day
Rates arrive as ".71"	Not "0.71" — a strict parser chokes	returns.to_float

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.