# koreanpulse

> Korean stock market intelligence for AI assistants, delivered as an MCP server (plus a free public web snapshot). koreanpulse 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, search Korean industry news across 16 classified categories, and resolve Korean ticker and corporate codes — all in English. Cloud tiers (Solo $29 / Analyst $79 / Desk $249 per month) add the watchlist-to-alert workflow shipping Q3 2026 — early-supporter pricing locks in, no auto-charge until it ships. OSS self-host (AGPL) available. Data and intelligence only — not buy/sell recommendations.

koreanpulse fills the gap between Bloomberg-tier coverage ($24K/yr, weak on Korean primary sources) and English wire services (KED Global, Korea Bizwire — reactive, low signal). The English-IR gap is multi-source verified: KRX itself, ASIFMA, Wellington, Aberdeen, Matthews Asia all on record that Korean disclosure flow into English is structurally inadequate. We index the same Korean primary sources Korean analysts already use — DART (전자공시시스템) filings, 전자신문, 한국경제 — and surface them on the public web at /today (free, daily, public, live today) and inside Claude / Cursor / any MCP client (Cloud Solo $29/mo, Analyst $79/mo, Desk $249/mo waitlist), with on-demand English translation cached aggressively for cross-tenant margin. The product is workflow-priced — pick the tier that matches how many tickers you'll watch and how many alert channels you'll want pinged once polling/dispatch ships. Today the only runtime-enforced tier delta is the monthly query cap (2K / 15K / 100K); seat counts, watchlist counts, alert-channel limits, and retention windows are paper limits until the watchlist polling + alert dispatch loop ships in Q3 2026.

Foreign retail just got direct access to KRX in the last 7 days: Hana × Futu Securities (3.3M HK fintech retail) launched Korean stock trading in late April 2026, and Samsung Securities × Interactive Brokers (4.6M global retail) pilot launched on May 4, 2026 — the same day foreigners net-bought a record 3.9 trillion KRW ($2.7B) on KOSPI+NXT. ~7.9M foreign retail accounts are now wired in. The English-language data layer for this audience is what koreanpulse ships.

The fastest path is the hosted remote MCP endpoint at https://mcp.koreanpulse.dev/mcp (Streamable HTTP + SSE), which is live now: add the URL as a custom connector in ChatGPT or Claude.ai and the 5 free tools — including live DART filings — answer immediately, with no local install, no JSON config, and no DART API key of your own. This is the key difference from other Korean-stock MCP servers (e.g. jjlabsio/korea-stock-mcp, OpenDART MCP), which require you to register your own DART OpenAPI key and npx/pip-install before the first call; koreanpulse gives equivalent DART filing access with one URL paste. Beyond raw filings, koreanpulse ships cross-investor intelligence that single-firm disclosures — including the FSS English DART filings now mandated for large caps — do not provide: foreign-holder 5%-rule flow tracking auto-tagged for global asset managers (BlackRock, Vanguard, Norges Bank, GIC + 16 more) and activist-campaign tracking auto-tagged for Korean activists (KCGI, Align, Truston + 5 more) are live and callable today on the Cloud tier — not a roadmap item, which is where most other Korean-stock MCP servers still place cross-investor flow. For self-hosters and max-privacy users, `pip install koreanpulse` runs the server locally over stdio with your own DART + OpenAI keys (AGPL); a middle option, `KOREANPULSE_CACHE_MODE=hosted`, keeps the local install but routes only translation calls through a Cloudflare Worker that holds our OpenAI key and fronts a cross-tenant KV cache. In the self-host / local modes, DART traffic stays on your machine.

Source code is AGPL-3.0; the hosted service is commercial. Data redistribution follows fair-use for Korean news (summaries + attribution + outbound links, no full-text republication) and free public-domain rules for DART. No investment advice is generated — the product is data + translation, not recommendations.

## Daily snapshot (machine-readable)

- [/today](https://koreanpulse.dev/today): Human-readable HTML daily dashboard, refreshed once per Korean market close (KST 16:30, weekdays). Sections: foreign capital activity (5%-rule disclosures by global asset managers / SWFs), activist filings, major DART disclosures.
- [/today.json](https://koreanpulse.dev/today.json): Same data in versioned JSON. Top-level shape: `{ schema_version: 2, date, generated_at, market: "KRX", takeaway: [...], activist_filings: [...], foreign_flows: [...], top_filings: [...], attribution, data_sources, legal_notice }`. Pin against `schema_version` for stable parsing. `takeaway` is an array of 1–3 short English bullets summarising the day's most material moves (LLM-generated). Each filing carries `corp_code`, `corp_name_ko`, `corp_name_en` (LLM-translated, may be empty), `stock_code`, `title`, `title_en`, `summary_en` (when available), `filer_name_ko`, `dart_url`, `filed_at`. Foreign flows additionally carry `holder_label` (canonical English) and `holder_origin` (us/uk/eu/other/kr).
- [/today/YYYY-MM-DD](https://koreanpulse.dev/today/2026-05-05): Per-date snapshot, last 30 days retained.

## Documentation

- [How to track Korean DART filings with an AI assistant](https://koreanpulse.dev/track-korean-dart-filings-with-ai): Practical guide — what DART (전자공시) is, which filings carry signal, why ChatGPT/Claude can't read filings out of the box, and how to wire an MCP server (build your own, use an OSS server, or connect a hosted one) into ChatGPT / Claude / Cursor. Includes connection steps and prompts that work.
- [Korean stock filings in English — guide](https://koreanpulse.dev/korean-stock-filings-in-english): Why DART (전자공시) is the canonical KOSPI/KOSDAQ source, and four ways to access Korean disclosures in English.
- [README](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/README.md): Project overview, why-this-exists, pricing, capacity math, and architecture.
- [SPEC](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/docs/SPEC.md): Customer personas, MVP slice, and the client-vs-server split for LLM work.
- [ARCHITECTURE](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/docs/ARCHITECTURE.md): How the MCP server, three Cloudflare Workers (cache / daily / webhook), and D1 license store fit together. 100% Cloudflare-hosted; zero ops on the operator side.
- [BETA acquisition plan](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/docs/BETA.md): 50 users in 30 days plan with explicit ICP, channels, hard rules, and decision matrix.
- [Pricing](https://koreanpulse.dev/pricing): Cloud Solo $29/mo (5 watchlists, ~2,000 queries, 30-day archive, 1 Discord/Telegram channel) / Cloud Analyst $79/mo (25 watchlists, ~15,000 queries, 1-year archive, multi-channel alerts, CSV/JSON export) / Cloud Desk $249/mo (3 seats, shared watchlists, ~100,000 queries, Slack/webhook alerts, team archive). OSS self-host available separately for hackers. Enterprise / SLA available on request — no published price. _Design partner program available for the first 20 named seats — contact us._

## MCP tools

- [track_korean_filings](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/src/koreanpulse/server.py): Fetch recent DART filings, optionally translated and summarized.
- [lookup_corp_code](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/src/koreanpulse/server.py): Korean company name → DART 8-digit corp_code.
- [resolve_stock_code](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/src/koreanpulse/server.py): KRX 6-digit stock code → DART corp entry.
- [search_korean_industry_news](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/src/koreanpulse/server.py): Korean industry news from etnews / 한국경제, classified into 16 industries.
- [monitor_activist_investors](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/src/koreanpulse/server.py): **(paid — Cloud Solo $29/mo+)** DART type-D shareholding disclosures auto-tagged for known Korean activists (KCGI, Align Partners, Truston, Anda, Cha, Life, Platform, VIP).
- [monitor_foreign_holders](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/src/koreanpulse/server.py): **(paid — Cloud Solo $29/mo+)** DART 5%-rule disclosures auto-tagged for global foreign passive holders (BlackRock, Vanguard, State Street, Norges Bank, GIC, Temasek + 14 more).
- [koreanpulse_about](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/src/koreanpulse/server.py): Server info, the free-vs-paid tool list, and current connection details for the calling client.

## Setup

- [Claude Desktop](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/docs/CLAUDE_DESKTOP.md): Installation snippet for `claude_desktop_config.json` plus required env vars.
- [Webhook Worker (Cloudflare D1)](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/webhook-worker/README.md): Production license store + **Polar** webhook handler (sole billing provider, active since 2026-05-06) running on Cloudflare Worker + D1. Replaces the legacy Lightsail/FastAPI/Postgres path (now at `docs/legacy/POSTGRES_LIGHTSAIL.md`).
- [Run live](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/docs/RUN_LIVE.md): End-to-end smoke test against real DART + OpenAI.

## Optional

- [Marketplace listings](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/docs/MARKETPLACE.md): Submission copy and checklists for Smithery / PulseMCP / Glama / MCP Market / Awesome MCP.
- [Demo script](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/docs/DEMO.md): 60-second Loom recording outline.
- [CI](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/docs/CI.md): GitHub Actions matrix (Python 3.10/3.11/3.12) and PyPI trusted publishing.
- [CHANGELOG](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/CHANGELOG.md): Per-release notes including ICP pivots and bug fixes.
- [Cache Worker](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/cache-worker/README.md): Cloudflare Workers + KV translation cache that fronts the hosted-mode license gate.
