korea-market-data-mcp

v0.30.0-alpha

Published

23 days ago

Read-only MCP server for Korean financial market data.

0High
0Medium
0Low

leokim99

mcp model-context-protocol korean-market-data kiwoom finance read-only

korea-market-data-mcp

Open-source Model Context Protocol server for reliable Korean financial market data access from AI agents.

korea-market-data-mcp helps AI tools such as Codex, Claude, ChatGPT, Cursor, and other MCP-compatible clients query Korean stocks, ETFs, indices, charts, and market data through structured provider adapters.

The first target provider is Kiwoom Securities REST API.

This project is intentionally read-only. It does not provide trading, order execution, automated trading, or personal account access.

Why this project exists

AI agents often fail to retrieve accurate and up-to-date Korean financial market data through generic web search.

Common problems include:

outdated stock and ETF prices
incorrect Korean ticker mapping
unreliable search snippets
mixed data sources without provenance
poor access to Korean ETF and index data
unsafe scraping-based workflows
no standard MCP interface for Korean market data

This project aims to provide a safer, structured, and maintainable bridge between AI agents and Korean financial market data providers.

Project goals

The goals of this project are:

Provide a read-only MCP server for Korean market data.
Help AI agents query structured stock, ETF, index, and chart data.
Start with Kiwoom Securities REST API as the first provider adapter.
Keep provider-specific credentials local to each user whenever possible.
Avoid unsafe scraping, credential sharing, and data redistribution risks.
Support future provider adapters such as KRX, ECOS, FRED, and other market data sources.
Make Korean financial data more accessible to developers, researchers, and AI-powered dashboards.

Non-goals

This project does not aim to provide:

stock trading
order execution
order cancellation
order modification
automated trading
portfolio management
personal account balance lookup
deposit or holdings lookup
investment advice
financial recommendations
centralized redistribution of licensed market data

The initial scope is strictly limited to read-only market data access.

Alpha launch candidate status

v0.30.0-alpha publishes the official npm alpha package for the read-only Kiwoom quote MCP alpha.

This project is:

a read-only MCP server
mock-provider first for setup and testing
local credential only for Kiwoom verification
guarded by safe defaults

This project is not:

a brokerage client
a trading bot
an account access tool
a centralized market data redistribution proxy
an investment recommendation system

Current alpha scope:

mock provider tools for local MCP testing
guarded get_kiwoom_stock_quote public tool skeleton
manual Kiwoom token and quote verification commands
documentation for Claude Desktop and Cursor setup
known limitations and release checklists
package metadata and local install/run documentation
alpha launch announcement and final review documentation
npm pack dry run and publish readiness documentation
clean install smoke test documentation
official npm publish decision documentation
official npm alpha publish result documentation

Real Kiwoom quote lookup remains disabled by default:

KIWOOM_ENABLE_REAL_API_CALLS=false
KIWOOM_ENABLE_PUBLIC_QUOTE_REAL_PATH=false

Kiwoom real local verification is explicit opt-in only. Endpoint enabled and exposesPublicTool defaults remain false.

Start with mock provider setup:

docs/getting-started/quickstart.md
docs/getting-started/mcp-client-setup.md
docs/getting-started/claude-desktop-setup.md
docs/getting-started/cursor-setup.md
docs/getting-started/troubleshooting.md
examples/README.md

Package and distribution readiness docs:

docs/release/distribution-readiness.md
docs/release/alpha-install-smoke-test.md
docs/release/v0.25.0-alpha-checklist.md
docs/release/alpha-launch-announcement.md
docs/release/alpha-final-review.md
docs/release/v0.26.0-alpha-checklist.md
docs/release/npm-pack-dry-run.md
docs/release/v0.27.0-alpha-checklist.md
docs/release/clean-install-smoke-test.md
docs/release/v0.28.0-alpha-checklist.md
docs/release/npm-publish-decision.md
docs/release/npm-access-policy.md
docs/release/versioning-policy.md
docs/release/v0.29.0-alpha-checklist.md
docs/release/npm-alpha-publish-result.md
docs/release/v0.30.0-alpha-checklist.md

Review safety and limitations:

SECURITY.md
docs/providers/provider-status.md
docs/release/alpha-known-limitations.md

Unsupported features remain explicitly out of scope:

No account access.
No orders.
No balance lookup.
No holdings lookup.
No trading.
No auto-trading.
No investment recommendations.
No centralized data redistribution proxy.

Planned MCP tools

Initial MCP tools may include:

search_korean_symbol
get_stock_quote
get_etf_quote
get_market_index
get_daily_chart

Future tools may include:

get_minute_chart
get_top_volume_stocks
get_top_value_stocks
get_foreigner_institution_flow
get_etf_basic_info
get_provider_status

All tools should return structured JSON responses that are easy for AI agents to interpret.

Provider adapter model

This project is designed around provider adapters.

MCP Client
  ↓
korea-market-data-mcp
  ↓
Provider Adapter
  ↓
External Market Data Provider

The first provider adapter target is:

Kiwoom Securities REST API

Potential future providers:

KRX
ECOS
FRED
Yahoo Finance
Other Korean market data providers

Provider-specific authentication, rate limits, response formats, and data licensing rules should be isolated inside each provider adapter.

Initial architecture

korea-market-data-mcp/
├─ src/
│  ├─ index.ts
│  ├─ server/
│  ├─ tools/
│  ├─ providers/
│  │  └─ kiwoom/
│  ├─ schemas/
│  ├─ safety/
│  └─ utils/
├─ docs/
│  ├─ architecture.md
│  ├─ provider-adapter-spec.md
│  ├─ security-model.md
│  └─ tool-spec.md
├─ examples/
│  └─ claude-desktop-config.json
├─ tests/
├─ .env.example
├─ package.json
├─ tsconfig.json
├─ README.md
├─ ROADMAP.md
├─ SECURITY.md
├─ CONTRIBUTING.md
└─ LICENSE

Security principles

This project handles financial data provider credentials, so security boundaries are important.

Core security principles:

Provider API keys must not be committed to the repository.
Secrets must be loaded from local environment variables.
The MCP server must not expose order or trading tools.
Market data tools must remain read-only.
Provider credentials should remain local to the user whenever possible.
Logs must not print API keys, access tokens, or secret values.
Provider adapters must clearly separate authentication, request signing, rate limits, and response normalization.
Tool schemas must not include dangerous hidden actions.
Any future account-related or trading-related functionality must be explicitly out of scope unless the project governance changes.

Environment variables

Create a .env file based on .env.example.

KIWOOM_APP_KEY=
KIWOOM_APP_SECRET=
KIWOOM_ENV=prod
KIWOOM_API_BASE_URL=https://api.kiwoom.com
KIWOOM_MOCK_API_BASE_URL=https://mockapi.kiwoom.com
CACHE_TTL_SECONDS=3
LOG_LEVEL=info

Do not commit .env.

Example use cases

Ask an AI agent for a Korean stock quote

Get the latest quote for Samsung Electronics using the Korean market data MCP.

Ask for ETF data

Check the current quote and recent daily chart for KODEX 200.

Ask for index data

Get the latest KOSPI and KOSDAQ index values.

Ask for dashboard data

Fetch current Korean ETF market data for my macro dashboard.

Local development

Option A: GitHub clone local setup

Clone the repository:

git clone https://github.com/farmbit-mdk/korea-market-data-mcp.git
cd korea-market-data-mcp

Install dependencies:

npm install

Copy environment variables:

cp .env.example .env

The default development provider is mock, so Kiwoom credentials are not required for the initial server skeleton.

Run the development server:

npm run dev

Run the built MCP server locally:

npm start

Build:

npm run build

Run tests:

npm test

The current implementation registers these read-only tools:

search_korean_symbol
get_stock_quote
get_kiwoom_stock_quote
get_etf_quote
get_market_index
get_daily_chart

get_kiwoom_stock_quote is a guarded Kiwoom-only skeleton. It is registered, but real Kiwoom quote lookup remains blocked by default.

Public MCP tool list:

search_korean_symbol
get_stock_quote
get_kiwoom_stock_quote
get_etf_quote
get_market_index
get_daily_chart

get_kiwoom_stock_quote is the only Kiwoom public quote tool. The tool is guarded, mock path is recommended first, real Kiwoom path remains local opt-in only, no account/order/trading tools exist, and future tools require separate review.

get_kiwoom_stock_quote is the only Kiwoom public quote tool.

Option B: Packaged or npm-ready setup

The package metadata is prepared for future npm distribution, but npm publish has not been performed for this release.

GitHub clone/local setup remains the primary distribution path. The npm package is not published yet, and npm publish readiness is still under review.

Do not install from unofficial npm packages claiming this project name. Use GitHub releases/source until an official npm package is published from this repository.

Tarball-based clean install smoke testing has been reviewed for the alpha package. Package-based setup remains alpha/testing only unless an official npm package is published.

Current package command shape:

package name: korea-market-data-mcp
package version: 0.30.0-alpha
main: dist/index.js
bin: korea-market-data-mcp -> dist/index.js
start: node dist/index.js

Until a package is actually published, use the GitHub clone path above.

v0.29.0-alpha records the official npm publish decision:

current decision: defer publish
recommended decision: defer actual npm publish until a separate final publish release
official npm package is not published yet
npm publish decision is being tracked
GitHub clone/local setup remains primary
package-based setup remains alpha/testing-only until official npm release
do not trust unofficial packages or hosted MCP proxies

Before any future npm publish, the maintainer must confirm package ownership, npm account access, 2FA, provenance, dist-tag, and versioning policy. If an alpha package is published in a future release, the recommended command is npm publish --tag alpha; alpha releases must not use the latest dist-tag.

v0.30.0-alpha publishes the official npm alpha package when the publish step succeeds:

npm install korea-market-data-mcp@alpha

Use the alpha tag during the alpha phase. Do not rely on the latest dist-tag for alpha releases.

GitHub clone/local setup remains supported and is the safe fallback. Mock provider remains the recommended first setup path. Real Kiwoom quote lookup remains disabled by default, and Kiwoom local verification remains explicit opt-in only.

See:

docs/release/npm-publish-decision.md
docs/release/npm-access-policy.md
docs/release/versioning-policy.md
docs/release/npm-alpha-publish-result.md
docs/release/clean-install-smoke-test.md
docs/release/npm-pack-dry-run.md
docs/release/distribution-readiness.md

Option C: MCP client local node command

For Claude Desktop, Cursor, and other MCP clients, build first and point the client at the built output:

{
  "command": "node",
  "args": [
    "/absolute/path/to/korea-market-data-mcp/dist/index.js"
  ],
  "env": {
    "MARKET_DATA_PROVIDER": "mock",
    "KIWOOM_ENABLE_REAL_API_CALLS": "false",
    "KIWOOM_ENABLE_PUBLIC_QUOTE_REAL_PATH": "false"
  }
}

Windows paths in JSON need escaped backslashes:

"C:\\absolute\\path\\to\\korea-market-data-mcp\\dist\\index.js"

See examples/README.md before editing client configuration.

Quick start and MCP client setup

v0.23.0-alpha adds user onboarding docs and MCP client setup examples.

Start here:

docs/getting-started/quickstart.md
docs/getting-started/mcp-client-setup.md
docs/getting-started/claude-desktop-setup.md
docs/getting-started/cursor-setup.md
docs/getting-started/troubleshooting.md

Use mock provider first:

examples/claude-desktop.mock.json
examples/cursor.mock.json
examples/env.mock.example

Kiwoom local verification examples are advanced and explicit opt-in only:

examples/claude-desktop.kiwoom-local.example.json
examples/cursor.kiwoom-local.example.json
examples/env.kiwoom-local.example

Real Kiwoom quote lookup remains disabled by default. KIWOOM_ENABLE_REAL_API_CALLS=false and KIWOOM_ENABLE_PUBLIC_QUOTE_REAL_PATH=false remain the safe defaults.

This project remains read-only:

no account access
no orders
no balance lookup
no holdings lookup
no trading
no auto-trading
no investment recommendations
no centralized data redistribution proxy

Kiwoom auth skeleton

The repository includes a Kiwoom provider auth skeleton for future adapter work. It can load Kiwoom-related environment variables and return normalized credential errors, but it does not request tokens or call the Kiwoom REST API by default.

Keep this flag disabled:

KIWOOM_ENABLE_REAL_API_CALLS=false

In v0.4.0-alpha development, the Kiwoom token client may call only its configured transport interface when KIWOOM_ENABLE_REAL_API_CALLS=true. Real API calls remain disabled by default, tests use mocked transport only, and live Kiwoom market data calls are still intentionally not implemented.

Kiwoom manual token verification

v0.6.0-alpha hardens the manual-only Kiwoom token verification workflow:

npm run kiwoom:token:manual

This command can make a real Kiwoom token request only when all of the following are true:

KIWOOM_ENABLE_REAL_API_CALLS=true
KIWOOM_APP_KEY=your-app-key
KIWOOM_SECRET_KEY=your-secret-key
KIWOOM_ENV=mock

The default remains KIWOOM_ENABLE_REAL_API_CALLS=false. Token values are never printed; the manual command only reports fields such as token_present, token_type, expires_dt, return_code, and return_msg.

This workflow does not add quote lookup, account access, order execution, balance lookup, holdings lookup, trading, auto-trading, or investment recommendation features. See docs/providers/kiwoom-manual-token-test.md.

Placeholder credential values such as YOUR_APP_KEY, YOUR_SECRET_KEY, CHANGE_ME, and REPLACE_ME are blocked before any manual token request is sent.

Kiwoom token error responses are normalized without printing raw request bodies, credentials, or token values.

Kiwoom quote adapter skeleton

v0.7.0-alpha adds a Kiwoom read-only quote adapter skeleton for provider-side development.

This is not live quote support yet:

real quote API endpoint is not finalized
tests use mocked quote transport
no new public MCP tool is registered
real API calls remain opt-in only

The skeleton intentionally excludes account access, orders, balance lookup, holdings lookup, trading, auto-trading, and investment recommendations.

Kiwoom quote endpoint mapping

v0.8.0-alpha adds documentation and disabled endpoint mapping constants for future Kiwoom read-only quote work.

This is still preparation only:

real quote lookup is not enabled
public MCP quote tool is not added
endpoint mapping remains disabled until official verification
tests use quote fixtures and mocked transport

No account, order, balance, holdings, trading, auto-trading, or recommendation features are added.

Kiwoom manual quote verification

v0.10.0-alpha hardens the guarded manual-only quote verification workflow:

npm run kiwoom:quote:manual

The command is blocked by default. It requires explicit real API opt-in, local credentials, a symbol, and an enabled read-only/manual-only endpoint mapping. The endpoint mapping remains disabled by default, so this release does not enable live quote lookup.

The workflow now documents and tests endpoint enabled/disabled policy, safe quote error normalization, malformed response handling, and redaction of app keys, secret keys, and access tokens.

No public MCP quote tool is added. Public real Kiwoom quote lookup is still not enabled. No account, order, balance, holdings, trading, auto-trading, or recommendation features are added.

Provider compliance and security review

v0.11.0-alpha adds provider compliance and security review documentation before any public provider-backed quote tool is exposed.

This is not a feature enablement release:

public MCP quote tool is still not added
public real Kiwoom quote lookup is still not enabled
credentials must remain local and must not be committed
centralized credential storage is out of scope
centralized market data redistribution proxy is out of scope
account, order, balance, holdings, trading, auto-trading, and recommendation features remain excluded

See:

docs/providers/provider-compliance.md
docs/providers/kiwoom-compliance-notes.md
docs/security/credential-handling.md
docs/release/public-quote-tool-readiness-checklist.md

Kiwoom public quote guarded skeleton

v0.15.0-alpha adds an explicit opt-in guard for the guarded public MCP tool skeleton:

get_kiwoom_stock_quote

The tool is registered so clients can validate the future public Kiwoom quote shape, but real Kiwoom quote lookup remains disabled by default. The guard returns blocked unless public exposure, endpoint mapping, real API opt-in, public quote real-path opt-in, credentials, token, and read-only checks are all explicitly satisfied.

Example input:

{
  "symbol": "005930",
  "market": "KOSPI",
  "provider": "kiwoom"
}

Default blocked output shape:

{
  "status": "blocked",
  "provider": "kiwoom",
  "symbol": "005930",
  "quote_present": false,
  "reason": "Kiwoom public quote tool is registered as a guarded skeleton but real quote lookup is not enabled."
}

Mock/test-only success output shape:

{
  "status": "ok",
  "provider": "kiwoom",
  "symbol": "005930",
  "quote_present": true,
  "quote": {
    "provider": "kiwoom",
    "symbol": "005930",
    "name": "Samsung Electronics",
    "market": "KOSPI",
    "currency": "KRW",
    "price": 70000,
    "change": 500,
    "change_rate": 0.72,
    "volume": 12000000,
    "as_of": "..."
  }
}

The symbol must be a 6-digit Korean stock code such as 005930. The input schema only allows symbol, market, and optional provider.

The guard order is intentionally conservative:

input object validation
forbidden field validation
symbol validation
provider validation
endpoint readOnly check
public exposure check
endpoint enabled check
real API opt-in check
public quote real-path opt-in check
credential and token checks
quote client call

Validation and blocked/error responses do not echo forbidden payload values, raw provider payloads, app keys, secret keys, or access tokens.

This release does not enable live Kiwoom quote support:

public real Kiwoom quote lookup is not enabled by default
KIWOOM_ENABLE_REAL_API_CALLS=false remains the default
KIWOOM_ENABLE_PUBLIC_QUOTE_REAL_PATH=false remains the default
provider credentials must remain local
centralized data redistribution proxy is not included
account, order, balance, holdings, trading, auto-trading, and recommendation features remain excluded

Real public Kiwoom quote lookup would require all of the following, and remains unavailable by default:

KIWOOM_ENABLE_REAL_API_CALLS=true
KIWOOM_ENABLE_PUBLIC_QUOTE_REAL_PATH=true

The endpoint mapping must also be enabled, marked read-only, and explicitly exposed as a public tool, with valid local credentials available. Account, order, balance, holdings, and trading behavior remain out of scope.

Local verification is documented in:

docs/providers/kiwoom-public-quote-local-verification.md

MCP request example:

{
  "symbol": "005930",
  "market": "KOSPI",
  "provider": "kiwoom"
}

Claude Desktop example

Example MCP configuration:

{
  "mcpServers": {
    "korea-market-data": {
      "command": "node",
      "args": [
        "/absolute/path/to/korea-market-data-mcp/dist/index.js"
      ],
      "env": {
        "KIWOOM_APP_KEY": "your-app-key",
        "KIWOOM_APP_SECRET": "your-secret-key",
        "KIWOOM_ENV": "prod"
      }
    }
  }
}

A complete example will be maintained in:

examples/claude-desktop-config.json

Additional MCP client examples:

examples/claude-desktop.mock.json
examples/claude-desktop.kiwoom-local.example.json
examples/cursor.mock.json
examples/cursor.kiwoom-local.example.json

Roadmap

v0.1 — Project foundation

README
LICENSE
SECURITY.md
CONTRIBUTING.md
ROADMAP.md
MCP server skeleton
Provider adapter interface draft
Tool schema draft

v0.2 — Kiwoom provider interface

Kiwoom auth wrapper
Token handling
Basic request client
Error normalization
Rate limit handling draft

v0.3 — Basic market data tools

search_korean_symbol
get_stock_quote
get_etf_quote
get_market_index
get_daily_chart

v0.4 — MCP client examples

Claude Desktop config
Cursor config
Codex local development workflow
Example prompts

v1.0 — First read-only release

Stable read-only market data tools
Documentation
Tests
Security review
Release notes

Contributing

Contributions are welcome.

Good first contribution areas:

provider adapter documentation
tool schema improvements
tests
response normalization
Korean ticker metadata
examples for MCP clients
security review
documentation improvements

Please read CONTRIBUTING.md before opening a pull request.

License

This project is licensed under the MIT License.

See LICENSE for details.

Disclaimer

This project is for software development, research, and data access tooling.

It does not provide investment advice, trading advice, brokerage services, financial recommendations, or automated trading functionality.

Users are responsible for complying with provider terms of service, data licensing restrictions, and applicable laws.

Verified mock provider test

The MCP server has been verified with Claude Desktop using the mock provider.

Test prompt:

Use korea-market-data MCP to get the stock quote for 005930.

Expected behavior:

Claude Desktop detects the korea-market-data MCP server.
The get_stock_quote tool is called.
The mock provider returns Samsung Electronics sample data.
The response includes provider: "mock".
The response must not be treated as live market data.

Example mock data:

| Field | Value | |---|---| | Symbol | 005930 | | Name | Samsung Electronics | | Market | KOSPI | | Price | 70,000 KRW | | Previous close | 69,500 KRW | | Change | +500 KRW | | Change rate | +0.72% | | Provider | mock |

Note: mock provider data is fixed sample data for local MCP testing only. It is not live market data and must not be used for investment decisions.

The mock provider also supports Korean alias search such as 삼성전자 → 005930 and 코덱스200 → 069500.

The Kiwoom provider is currently an authentication skeleton only. It validates local credential configuration but does not make real Kiwoom API calls by default.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

korea-market-data-mcp

Why this project exists

Project goals

Non-goals

Alpha launch candidate status

Planned MCP tools

Provider adapter model

Initial architecture

Security principles

Environment variables

Example use cases

Ask an AI agent for a Korean stock quote

Ask for ETF data

Ask for index data

Ask for dashboard data

Local development

Option A: GitHub clone local setup

Option B: Packaged or npm-ready setup

Option C: MCP client local node command

Quick start and MCP client setup

Kiwoom auth skeleton

Kiwoom manual token verification

Kiwoom quote adapter skeleton

Kiwoom quote endpoint mapping

Kiwoom manual quote verification

Provider compliance and security review

Kiwoom public quote guarded skeleton

Claude Desktop example

Roadmap

v0.1 — Project foundation

v0.2 — Kiwoom provider interface

v0.3 — Basic market data tools

v0.4 — MCP client examples

v1.0 — First read-only release

Contributing

License

Disclaimer

Verified mock provider test