io.github.juh5ng/k-data-mcp
Korean market data: kimchi premium, sell-side research, news. Pay per call in USDC via x402.
Open source Open in the app JSON README (API)
About
Korean market data: kimchi premium, sell-side research, news. Pay per call in USDC via x402.
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- juh5ng
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.2.1
- Last push
- 2026-09-06T01:23:53Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:00:17
- Updated
- 2026-08-29 04:00:17
- Origin id
io.github.juh5ng/k-data-mcp
README
# k-data-mcp
MCP server for **Korean equity research and market data**, metered per call in USDC over [x402](https://x402.org). Start it without a wallet to inspect the catalog and run free, date-stamped previews; add a dedicated wallet only when you want paid calls.
## Try before funding a wallet
Run `npx k-data-mcp` with no environment variables to use these free tools:
- `list_endpoints` — paid catalog and prices.
- `preview_research_coverage` — real per-ticker report/brokerage counts and archive date ranges.
- `preview_research` — a single ticker's actual archive depth; this does not disclose report content.
- `preview_kimchi_premium` — live BTC-only dual-basis sample.
Set `K_DATA_PRIVATE_KEY` and `K_DATA_MAX_SPEND_USD` only when you are ready to enable paid tools.
## What you get
- **Kimchi premium on a tradeable basis.** Everyone quotes the premium against the official USD/KRW rate, but Korean capital controls mean the KRW exit leg actually goes through USDT — so that number is not something you can trade on. This returns both, and they routinely disagree *in sign*: official can read −0.27% while the realizable basis is +0.19%.
- **Premium history and percentile context.** A continuously recorded archive answers "is this premium unusual right now?" — percentile, mean, stdev, z-score over 1h–90d. No free source publishes this, and it cannot be reconstructed after the fact.
- **Korean headlines translated to English**, from Yonhap, Maeil Business and Hankyung. Korean myriad units (억 / 조) are expanded deterministically before translation, so "989억달러" comes back as *$98.9 billion* rather than the 10×-off answer language models produce unaided.
- **Korean sell-side research as structured data.** Target prices, ratings, brokerage and analyst per KRX ticker, each with an English summary, plus the consensus and revision history built from them — who raised, who cut, and how far apart the houses actually are. Only the facts of each report are sold, in our own words, with a link back to the publisher; the report PDF stays with the brokerage that wrote it. The listing source shows a rolling recent window only, so this series cannot be reconstructed after the fact either.
- Upbit KRW quotes and market summaries, USD/KRW.
## Install
```bash
npx k-data-mcp
```
### Claude Desktop / Claude Code
```json
{
"mcpServers": {
"k-data": {
"command": "npx",
"args": ["-y", "k-data-mcp"],
"env": {
"K_DATA_PRIVATE_KEY": "0xYOUR_DEDICATED_WALLET_KEY",
"K_DATA_MAX_SPEND_USD": "1"
}
}
}
}
```
## Wallet setup
Each tool call spends real USDC, so the server will not start without a key and a budget.
1. Create a **dedicated** wallet — not your main one. The key sits in a config file and every call spends from it.
2. Fund it with the USDC you're willing to spend on Base. **No ETH needed**: x402 settles with an off-chain EIP-3009 signature and the facilitator pays the gas.
3. Set `K_DATA_MAX_SPEND_USD`. The server refuses any call that would push cumulative spend past it.
| Variable | Required | Default | Meaning |
|---|---|---|---|
| `K_DATA_PRIVATE_KEY` | yes | — | Private key of the paying wallet (USDC on Base) |
| `K_DATA_MAX_SPEND_USD` | no | `1` | Hard cap on cumulative spend for the session |
| `K_DATA_BASE_URL` | no | hosted service | Point at a different K-Data deployment |
## Tools
`list_endpoints` is **free** — call it first to see current prices and decide what's worth buying.
| Tool | Price | Returns |
|---|---|---|
| `list_endpoints` | free | Catalog, current prices, wallet address, remaining budget |
| `kimchi_premium` | $0.03 | Dual-basis premium (official + USDT) for up to 10 coins |
| `kimchi_premium_stats` | $0.12 | Percentile, mean, stdev, z-score of the premium over 1h–90d |
| `kimchi_premium_history` | $0.08 | Premium time series, both bases |
| `korea_market_snapshot` | $0.08 | One-call briefing: premium + markets + FX + translated headlines |
| `research_consensus_ticker` | $0.12 | Analyst consensus for one KRX ticker — target price mean/median/range and spread, rating mix, and every house's revision history |
| `research_company_ticker` | $0.05 | Archived Korean brokerage reports for one ticker, summarised in English |
| `research_latest` | $0.02 | Latest Korean equity research across all covered companies |
| `news_headlines_en` | $0.05 | Korean headlines with English translations |
| `crypto_krw_markets` | $0.01 | All Upbit KRW markets — volume leaders, gainers, losers |
| `news_headlines` | $0.01 | Korean headlines, untranslated |
| `crypto_krw_ticker` | $0.005 | One Upbit KRW quote |
| `fx_usdkrw` | $0.005 | USD/KRW rate |
Prices are read from the provider's catalog at startup, so this table reflects whatever the service currently charges.
## How payment works
Every paid endpoint answers an unpaid request with `HTTP 402` and a `PAYMENT-REQUIRED` header describing the price, asset and recipient. This server signs an EIP-3009 authorization for that exact amount and retries; the facilitator settles it on Base. Nothing is held on account — you pay per call, and stop paying when you stop calling.
## License
MIT