koreanpulse

[koreanpulse]

koreanpulse

Korean stock disclosures, activist filings & foreign-holder flows in English — for AI agents via MCP.

Korean stock market intelligence for AI assistants. koreanpulse is an MCP server that connects ChatGPT / Claude / Cursor / FastMCP agents to Korean (KRX / KOSPI / KOSDAQ) equity data — track DART corporate disclosures as they are filed, monitor foreign investor holding changes and activist investor campaigns, and search classified Korean industry news, all in English. Data and intelligence only — not buy/sell recommendations.

The goal: get pinged in English when a 5%-rule filing or DART event hits a stock you care about. (Beta — watchlist polling + alert dispatch are planned and not yet available; what works today is on-demand queries.)

The pitch: koreanpulse translates, tags, and filters Korean primary-source disclosure data — foreign-holder 5%-rule disclosures, Korean activist filings, major DART events — for AI assistants. KRX itself, ASIFMA, and several global asset managers are on record that Korean disclosure flow into English is structurally thin. Free public daily snapshot at /today; paid Cloud tiers (Solo $29/mo, Analyst $79/mo, Desk $249/mo) cover the two allowlist-tagging tools, which run only on the hosted service and are unavailable while it is paused since 2026-09-21 — watchlist polling + alert dispatch are planned and not yet available; early subscribers keep their signup rate when those land. OSS self-host available for hackers — see Run it yourself.

For AI/MCP agent builders. koreanpulse plugs Korean equity primary sources into your existing Claude Desktop / Cursor / FastMCP agent — same MCP shape your agent already uses for US data. Two connection modes: (a) pip install koreanpulse + 4-line config for Claude Desktop / Cursor stdio, (b) Smithery marketplace listing for Smithery CLI users. The first-party hosted remote MCP endpoint (https://mcp.koreanpulse.dev/mcp) has been paused since 2026-09-21; use the self-hosted install, which runs the 5 free tools (the 2 license-gated tools, activist and foreign-holder tagging, run only on the hosted service). The 7 tools surface DART filings, foreign-holder 5%-rule flows, Korean activist filings, and 16-sector industry news as typed function calls; the rest of your trading-agent stack stays unchanged.

Claude.ai / ChatGPT (remote MCP) — hosted endpoint paused. The first-party hosted endpoint https://mcp.koreanpulse.dev/mcp has been paused since 2026-09-21 and does not respond, so it cannot be added as a custom connector right now. Use the self-hosted install instead: pip install koreanpulse and the Claude Desktop / Cursor config in docs/SELF_HOSTING.md (you supply your own DART API key; this covers the 5 free tools, since the 2 license-gated tools run only on the hosted service). The free public /today snapshot at koreanpulse.dev is unaffected. Read-only — surfaces filings and disclosures only. No trading execution, no investment advice.

What this server answers (capability vector for agent retrieval). Korean DART (전자공시) filings on any KOSPI / KOSDAQ / KONEX / KRX ticker; 5%-rule shareholding disclosures tagged against a maintained allowlist — Korean activist filers (KCGI / Align Partners / Truston Asset / Anda Asset / Cha Partners / VIP Asset / Life Asset / Platform Partners / Must Asset Management / Dalton Investments / Flashlight Capital Partners / Oasis Management / Palliser Capital / Whitebox Advisors / City of London Investment Management + ValueAct / Elliott when filing in Korea) and global foreign holders (BlackRock / Vanguard / State Street / Fidelity / Capital Group / T. Rowe Price / Wellington / Matthews Asia / Templeton / Aberdeen / Schroders / Norges Bank / GIC / Temasek / Goldman Sachs / JPMorgan / Morgan Stanley / Citadel / Millennium / Bridgewater); Korean industry news across 16 sectors (semiconductor / shipbuilding / battery / biotech / defense / auto / EV charging / AI / steel / petrochem / construction / fintech / gaming / e-commerce / telco / energy) sourced from 전자신문 + 한국경제 + The Korea Herald (English-native) + 지디넷코리아. All with on-demand English translation cached server-side. Tool catalog and example queries are also returned by koreanpulse_about for agent-side capability discovery.

Status

Pre-alpha (v0.1.13). 7 MCP tools shipped — 5 free + 2 license-gated (activist + foreign-holder allowlist tagging, Solo $29/mo+; these two run only on the hosted service, which is paused since 2026-09-21). 418 tests pass. Beta — watchlist polling + alert dispatch are planned and not yet available. Beta acquisition plan in docs/BETA.md.

Why I built this

I'm a Seoul-based developer. I kept watching English-speaking friends miss the Korean disclosure that would have flipped their KOSPI trade — KCGI filing on a value-up target, BlackRock crossing 5% on an HBM name, an activist quietly accumulating. The Korean primary source (DART 전자공시) is unambiguous; English coverage is often hours late or absent. I wanted a thing they could plug into the chat assistant they already use, ask "anything new on Samsung Electronics?", and get the same answer I'd get reading DART directly. That's koreanpulse.

I run it as MCP because that's the shape of stack the people I'd want to use this already have — Claude Desktop, Cursor, the OpenAI Responses API, ChatGPT custom connectors. No new client to install. Free tier is the daily snapshot and the five free tools; the two license-gated tools (5%-rule allowlist tagging on activists and foreign holders) are the part that takes a Korean speaker hours to do by hand.

Why this exists

"Majority of foreign investors find it surprisingly difficult to penetrate the Korean hedge fund market due to its limited accessibility and availability of information in foreign language." — HedgeVista, 2025

"Published information should be made available in both Korean and English for all investors." — ASIFMA Korean Capital Markets Report, 2022

"The Korea Exchange will provide investor relations services to companies that lack the capability, particularly in English." — Wellington Management on Korea Value-Up program, 2025

The English-IR gap is multi-source verified. The triggers below sit on top of it:

• Broker access keeps widening — Hana Securities × Futu launched Korean stock trading for Futu's Hong Kong retail customers (April 2026), and Samsung Securities × Interactive Brokers launched a pilot (May 2026)
• KOSPI has been under review for MSCI Developed Market reclassification — one reason global investors track Korean market-access changes
• IRC (Investor Registration Certificate) requirement abolished 2023-12-14, removing the decades-old registration step for foreign investors' direct KRX access
• Millennium made its first Korean allocation ($250M to Billionfold) in 2025
• Korean activist scene maturing (KCGI, Align Partners) + global activists filing in Korea (ValueAct, Elliott)
• Korean shipbuilding, HBM, defense, biotech all globally relevant — but Korean-only sourcing
• Korean retail rotated heavily out of crypto into KOSPI ($110B left Upbit/Bithumb in 2025)
• Bloomberg/FactSet enterprise tier only — indie/SMB tier empty

Who pays

The free daily snapshot at /today (no login, no API key) is the funnel front door — the same classified data the paid tools query, published once per weekday.

Design partner program available for the first 20 named seats — contact us.

Pricing

🚧 Beta. Solo $29 / Analyst $79 / Desk $249. Checkout is closed while the hosted service is paused (since 2026-09-21); plan names and prices are kept below for when it resumes. Once the hosted service resumes, a paying user receives immediately: the two license-gated allowlist-tagging tools, hosted translation, and the metered query cap (2K / 15K / 100K). Watchlist polling, alert dispatch, seat enforcement, and per-tier retention windows are planned and not yet available — until they ship, seat counts, watchlist counts, alert-channel limits, and archive-retention windows are paper limits, and most tier differentiation is roadmap. Early subscribers keep their signup rate when those features land. The hosted service has been paused since 2026-09-21, so the two license-gated tools are currently unavailable to everyone, license holders included.

30-day refund window on first payment.

Subscribe: paused — checkout is closed while the hosted endpoint is paused (since 2026-09-21). Plans stay listed at koreanpulse.dev/#pricing. Per-tier Polar checkouts (Solo / Analyst / Desk) return when it resumes, each covered by Polar as Merchant of Record (sales tax / VAT / refunds handled); the license key is emailed by the webhook worker on subscription.created.

Enterprise / SLA: contact us. No published price.

Run it yourself (OSS)

Source is AGPL-3.0. Self-hosters can run the MCP server locally with their own DART and OpenAI keys. This path is for hackers and max-privacy users.

OSS self-host is not in the pricing table above — it's a separate lane. See docs/SELF_HOSTING.md for the install + key wiring. Note: the OSS-vs-Cloud table above covers the pip-install paths. A zero-install path existed — the hosted remote MCP at https://mcp.koreanpulse.dev/mcp — but it has been paused since 2026-09-21; use the self-hosted pip install koreanpulse path for now. While the hosted service is paused, the Cloud column above is on hold: Cloud licenses cannot currently be used, and a self-install does not include the two license-gated tools.

Tools

7 MCP tools shipped — 5 free + 2 license-gated. Callable from Claude Desktop / Cursor / any MCP client; the 5 free tools run in a self-install, while the 2 license-gated tools run only on the hosted service, which is paused since 2026-09-21. The paid tier unlocks the allowlist-tagging work that takes a Korean speaker to do by hand; the free tier ships the raw DART + RSS surface.

Free tier (no license_key, no signup):

Paid tier (Solo $29/mo+, requires license_key — pass as tool argument or via the calling client's secure-input field):

When a paid tool is called without a license, the server returns a short notice explaining that a license key is required. No checkout link is included in the tool response.

4 more planned (docs/SPEC.md): digest_analyst_reports, get_ma_pipeline, track_government_policy, summarize_korean_earnings_call.

Differentiation vs incumbents

Differentiation vs other Korean MCP servers

A handful of Korean-data MCP servers exist. Pick what matches your job. We focus on English-first equity data with allowlist-based filer tagging, with a self-hosted install (the hosted endpoint is paused since 2026-09-21). If you need raw KRX OHLCV or Korean-language financial-statement tables, others do that better.

Other servers in the space (different scope or smaller install base): SongT-50/korean-stock-mcp, koreal6803/finlab-ai (quant-focused), eddmpython/dartlab (Python lib). Comparison last verified 2026-05-07 — other projects may have shipped changes since.

Capacity (DART quota math)

DART caps each API key at 40,000 calls/day (verified 2026-05). We enforce a soft cap at 32,000/day (80%) with DART_DAILY_QUOTA env override.

Filing-list responses go through list_filings_cached() with a freshness-aware TTL (60s for today's window, 1h for ≤6d old, 24h for ≥7d old). Cache hits don't burn DART quota.

Hard ceiling: ~30,000 MAU per DART key. Second key (separate 사업자등록번호) required beyond that.

Forecast 12mo mix (756 MAU) sits at ~930 DART calls/day = 2.9% of soft quota with 70% cache. ~34× headroom to scale before quota engineering.

See src/koreanpulse/cache.py, src/koreanpulse/dart.py:list_filings_cached.

Roadmap

Available now: queries (DART filings and industry news via self-install; foreign-holder + activist tracking runs only on the hosted service, paused since 2026-09-21), hosted translation cache (Cloud KOREANPULSE_CACHE_MODE=hosted), /today daily snapshot, Polar → D1 license issuance (Polar is our sole billing provider and Merchant of Record). The first-party hosted MCP endpoint (https://mcp.koreanpulse.dev/mcp) is paused since 2026-09-21; use the self-hosted pip install koreanpulse path.

Planned — not yet available:

• Watchlist polling loop (Cloudflare cron + koreanpulse.alerts)
• Alert dispatch enforcement (Discord / Telegram / Slack / webhook)
• Per-tier limit enforcement: watchlist count, alert-channel count, archive retention, seat count

Earlier milestones:

• W1–2 ✅ project skeleton, FastMCP server, DART client, agentprod integration
• W3–4 ✅ MVP: track_korean_filings, lookup_corp_code, search_korean_industry_news, translation layer with cache
• W5–6 ✅ Webhook handler skeleton (license auto-issuance) — Polar billing
• W5–6 ✅ Cloudflare D1-backed LicenseStore (replaces in-memory)
• W7–8 ⏳ Watchlist polling + alert dispatch (planned, not yet available) — wiring cache-worker cron + daily-worker cron + koreanpulse.alerts module into the watchlist-to-alert workflow that powers Solo / Analyst / Desk. D1 schema and alert-dispatch primitives already shipped; the cron loop is the missing piece.
• W7–8 digest_analyst_reports, summarize_korean_earnings_call
• W9–10 Multi-seat / shared watchlists for Cloud Desk
• W11–12 First paid customer

Architecture

• MCP server — FastMCP (Python), runs on the user's machine over stdio. Zero hosting cost on our side. Cloud customers still install this locally; switching KOREANPULSE_CACHE_MODE=hosted routes translation calls (only) to the Worker.
• Cache Worker (cache-worker/) — Cloudflare Workers + KV. Holds our OpenAI key, fronts a global translation cache, gates each call behind a license check. Free tier (100K req/day Workers + 100K read/day KV) covers paid traffic until well past $5K MRR.
• Daily Worker (daily-worker/) — Cloudflare Workers + KV. Cron-driven /today dashboard build (KST 16:30 weekdays).
• Webhook Worker (webhook-worker/) — Cloudflare Worker + D1 (SQLite). Handles Polar billing events (Polar is our sole billing provider, active 2026-05-06+) and /v1/validate for the Cache Worker. Replaces the old Lightsail/FastAPI/Postgres stack so the operator runs zero servers.
• Reuses agentprod — Throttle, Retry, CostTracker.

OSS self-host vs Cloud

Two ways to run the MCP, switched via KOREANPULSE_CACHE_MODE. Both require a local install (pip install koreanpulse + 4-line Claude Desktop config); the difference is whether translation calls go through our Worker or directly to OpenAI from your machine.

(Quick-start comparison also appears in "Run it yourself" above — keep both in sync when editing.)

Cache hits are the entire reason a $29/mo Solo plan can sustain healthy gross margin: the same Korean filing title gets translated once, then served to every other tenant on the same plan from KV. See docs/CLAUDE_DESKTOP.md for the env-var split between modes.

Hosted HTTP transport — paused since 2026-09-21. The first-party endpoint https://mcp.koreanpulse.dev/mcp (Streamable HTTP) was last validated end-to-end against ChatGPT and Claude.ai on 2026-05-06 and is currently switched off; it does not respond. The HTTP transport code (koreanpulse.mcp_http) remains in the repository for self-hosters. The local stdio install path remains canonical for self-hosters and max-privacy users; the Smithery listing keeps Smithery CLI users in the discovery path.

Legal posture

• Korean news: short summaries with attribution + outbound links only, no full-text republication. Summaries are generated from public RSS feed metadata.
• DART data: retrieved via the DART open API with attribution; every item links to the original filing. Underlying filings remain subject to their own applicable rules.
• Korean broker reports: not ingested (paywalled reports excluded).
• No spatial / mapping data is used.
• Not investment advice. koreanpulse provides disclosure data, translation, filtering, and tagging. It does not execute trades and does not provide personalized buy/sell recommendations; no individualized analysis is performed. All output is general data intended for informational purposes only.
• Users should assess the licensing, data-use, and financial-services obligations that apply to their own jurisdiction and use case, especially when redistributing data downstream. Nothing in this repository is legal advice.
• Privacy + data protection: see https://koreanpulse.dev/privacy — covers Korea PIPA, EU GDPR, US CCPA. Terms of service: https://koreanpulse.dev/terms.

Billing (Polar — active provider)

Billing runs on the webhook-worker/ Cloudflare Worker + D1 (SQLite). The operator runs zero servers.

Active provider: Polar (polar.sh) — Merchant of Record since 2026-05-06. Handles VAT / sales tax / refunds / chargebacks for all subscriptions. License keys are emailed automatically on subscription.created via the webhook worker.

Lemon Squeezy: removed. Their store application was declined on 2026-05-06; we did not appeal. No LS variant secrets are configured in production and no LS webhook deliveries are accepted. The Python LS handler (koreanpulse.billing) and the koreanpulse-webhook entry point were removed from the repository on 2026-10-18. The webhook-worker route /webhook/lemonsqueezy is a no-op and goes away at the next worker deploy — Polar is the sole billing provider.

See webhook-worker/README.md for the full deploy + secrets walkthrough; the short version:

cd webhook-workernpm installnpx wrangler d1 create koreanpulse_db   # paste returned id into wrangler.tomlnpm run migrate:prod                     # applies 0001_licenses.sql + 0002_pricing_v2.sql
# ── Polar (active provider) ──────────────────────────────────────────npx wrangler secret put POLAR_WEBHOOK_SECRET    # `polar_whs_...` from Polar webhook pagenpx wrangler secret put POLAR_API_TOKEN         # `polar_oat_...` (subscriptions:read scope)npx wrangler secret put POLAR_PRODUCT_SOLO      # UUID of Cloud Solo productnpx wrangler secret put POLAR_PRODUCT_ANALYST   # UUID of Cloud Analyst productnpx wrangler secret put POLAR_PRODUCT_DESK      # UUID of Cloud Desk product
# ── Shared ───────────────────────────────────────────────────────────npx wrangler secret put KOREANPULSE_CACHE_SHARED_SECRET   # same value cache-worker uses
npm run deploy

Endpoints (deployed to https://api.koreanpulse.dev or https://koreanpulse-webhook.<account>.workers.dev):

• GET /health → {"status":"ok"}
• POST /webhook/polar → Standard Webhooks signature verified (webhook-id / webhook-timestamp / webhook-signature), idempotent on webhook-id
• POST /webhook/lemonsqueezy → removed from use (no-op route, deleted at the next worker deploy — see Billing note above)
• POST /v1/validate → HMAC-signed by the cache-worker, validates license + atomically increments period counter

Polar events handled: subscription.created / .active / .updated / .canceled / .revoked. Auto-issues license keys, upgrades plans in place, deactivates on cancellation. License rows are tagged with metadata.provider = "polar" so the source is traceable per row.

The earlier path (Python koreanpulse-webhook FastAPI on Lightsail + Postgres) is superseded as of 2026-05-05 and its code was removed on 2026-10-18; for operator memory it lives at docs/legacy/POSTGRES_LIGHTSAIL.md. New deploys should use the Cloudflare Worker path.

Distribution / marketplaces

Listing copy + submission checklists in docs/MARKETPLACE.md:

• First-party hosted endpoint — https://mcp.koreanpulse.dev/mcp — paused since 2026-09-21; use pip install koreanpulse
• Smithery — marketplace listing for Smithery CLI users
• PulseMCP — not yet submitted (deferred)
• Glama — live (auto-discovered, score badge)
• Awesome MCP — PR #5893
• MCP Market — Smithery ingest (auto)
• mcp.so — live (manual submission)
• MCP Registry (registry.modelcontextprotocol.io) — published

Beta acquisition (50 users in 30 days) plan + crypto-native channel mix in docs/BETA.md. Demo recording script in docs/DEMO.md. CI / PyPI release pipeline in docs/CI.md.

Alert primitives (library — the hosted watchlist→alert loop is not yet available)

The koreanpulse.alerts module ships the dispatch primitive that the planned watchlist workflow will use. koreanpulse.alerts.send_alert(url, title=, body=) sends to any of:

• Discord webhooks (https://discord.com/api/webhooks/...)
• Slack incoming webhooks (https://hooks.slack.com/services/...)
• Telegram bots (shortcut tg://<bot_token>/<chat_id> or full sendMessage URL)

Fire-and-forget — transport / formatting failures return AlertResult(ok=False) instead of raising, so an outage in one channel never breaks a tool call. See src/koreanpulse/alerts.py.

Example prompts

Copy-paste these into Claude.ai, ChatGPT, or any MCP client connected to a self-installed koreanpulse server (the hosted endpoint is paused since 2026-09-21):

Ask Claude: "What DART filings were submitted for Samsung Electronics in the last 7 days?"

Ask Claude: "Look up the DART corp code for Kakao and show me its latest disclosures."

Ask Claude: "Any Korean semiconductor news this week from 전자신문?"

Ask Claude: "Which activist investors filed 5%-rule disclosures on KOSPI stocks this month? [license_key: YOUR_KEY]"

Ask Claude: "Show me recent foreign-holder 5%-rule filings — has BlackRock or Norges Bank crossed any thresholds? [license_key: YOUR_KEY]"

The first three prompts use free tools (no signup). The last two use the activist and foreign-holder allowlist tagging, which runs only on the hosted service (paused since 2026-09-21) and requires a Solo $29/mo license key; a self-install cannot use them — the server returns a short notice explaining that a license key is required if license_key is missing (no checkout link in the response).

License

Source: AGPL-3.0-or-later. Hosted service: commercial.

Copyright (C) 2026 Lee Jong-guk (이종국)

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. It is distributed WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See LICENSE for the full text, or https://www.gnu.org/licenses/.