Korea Stocks

Kakao PlayMCP registration skeleton for a read-only Korean stocks MCP server.

The current implementation is mostly a tool skeleton. KIS integrations and most DART tools are not implemented yet, while dart_search_filings calls the OpenDART disclosure search API, dart_get_company_overview calls the OpenDART company overview API, and dart_get_financial_statement calls the OpenDART single-company major accounts API.

Korean docs:

• Railway deployment guide: docs/RAILWAY_DEPLOY_KO.md
• PlayMCP container registry guide: docs/PLAYMCP_CONTAINER_REGISTRY_KO.md
• Handoff for KIS/DART implementers: docs/HANDOFF_KO.md
• Development conventions: docs/CONVENTIONS_KO.md
• MCP server operating baseline: docs/MCP_BEST_PRACTICES_KO.md
• Testing guide: docs/TESTING_KO.md

Requirements

• Node.js 22+
• npm

On Windows PowerShell, use npm.cmd if script execution blocks npm.ps1.

Setup

npm.cmd install
Copy-Item .env.example .env
npm.cmd run dev

The local server defaults to:

• Health check: http://127.0.0.1:3000/health
• MCP endpoint: http://127.0.0.1:3000/mcp

For PlayMCP, deploy behind HTTPS and register:

https://<your-domain>/mcp

Tool Scope

Registered data tools:

• resolve_stock
• get_stock_master
• stock_get_quote
• stock_get_orderbook
• stock_get_price_history
• market_get_index
• market_get_sector
• market_get_news
• market_get_movers
• dart_get_company_overview
• dart_get_financial_statement

Registered system tool:

• system_health

Trading and account tools are intentionally not included. Do not add account_*, order_*, order execution, order cancellation, balance, or account-number dependent tools to this read-only server.

Inspector

After starting the server, use MCP Inspector with Streamable HTTP and connect to:

http://127.0.0.1:3000/mcp

You should see the tools listed above. KIS tools require KIS credentials, DART tools require DART_API_KEY, and system_health returns basic server status.

DART Filings Search Example

Set DART_API_KEY in .env, start the server, and call dart_search_filings through an MCP client.

Example arguments:

{
  "companyName": "삼성전자",
  "start_date": "20240101",
  "end_date": "20241231",
  "disclosure_type": "ALL",
  "final_only": true,
  "page": 1,
  "page_size": 20
}

You can also use a supported stock code or a DART corporation code:

{
  "stockCode": "005930"
}

{
  "corp_code": "00126380"
}

The tool resolves companyName, stockCode, or stock_code to an OpenDART corp_code, calls list.json, and returns normalized filing rows with DART filing URLs in the common envelope. If disclosure_type is ALL, the OpenDART pblntf_ty parameter is omitted.

DART Company Overview Example

Set DART_API_KEY in .env, start the server, and call dart_get_company_overview through an MCP client.

Example arguments:

{
  "companyName": "삼성전자"
}

You can also use a supported stock code:

{
  "stockCode": "005930"
}

The tool resolves companyName or stockCode to an OpenDART corp_code, calls company.json, and returns normalized company overview fields in the common envelope.

DART Financial Statement Example

Set DART_API_KEY in .env, start the server, and call dart_get_financial_statement through an MCP client.

Example arguments:

{
  "companyName": "삼성전자",
  "year": "2023",
  "reportCode": "11011"
}

You can also use a supported stock code:

{
  "stockCode": "005930",
  "year": "2023"
}

한국어 companyName 입력은 data/stock_data_ko.json에서 종목명을 검색한 뒤, 해당 종목코드를 DART corp_code로 매핑합니다. 한국어 종목명은 공백을 제거해 비교하므로 삼성 전자 같은 입력도 삼성전자로 조회할 수 있습니다. 영문 companyName 입력은 trim 후 대문자로 normalize하여 data/stock_data_en.json에서 검색하므로 NAVER, Naver, naver처럼 대소문자가 달라도 동일한 영문 종목명으로 조회됩니다.

The DART resolver now loads OpenDART corpCode.xml data, parses the ZIP-contained XML, and keeps a 24-hour in-memory stock_code -> corp_code cache so listed companies can be resolved without hardcoding each mapping. If DART_API_KEY is missing, OpenDART is unavailable, or parsing fails, the resolver falls back to the built-in mappings for 삼성전자, SK하이닉스, and LG에너지솔루션. If neither OpenDART data nor fallback contains the stock code, the tool returns a clear unsupported corp_code mapping error. The response is wrapped in the common envelope and summarizes revenue, operating income, net income, total assets, total liabilities, and total equity.

DART financial statement accounts are matched with conservative aliases for common OpenDART account-name variants. When consolidated (CFS) and separate (OFS) rows are both available for the same alias, the consolidated row is preferred.

MVP 로컬 검증 결과

PR #1부터 PR #5까지 merge한 뒤, 로컬 환경에서 실제 OpenDART API를 호출해 DART MVP 흐름을 검증했습니다.

검증 환경:

• MCP endpoint: http://127.0.0.1:3000/mcp
• 로컬 .env에 DART_API_KEY 설정
• mock이 아닌 실제 OpenDART API 호출로 검증

검증 완료 케이스:

Tool	입력값	결과	비고
dart_get_company_overview	현대차	성공	KOSPI, stock_code 005380, corp_code 00164742
dart_get_financial_statement	현대차	성공	2023년 사업보고서 기준, 주요 6개 계정 반환: revenue, operating_income, net_income, total_assets, total_liabilities, total_equity
dart_get_company_overview	카카오	성공	KOSPI, stock_code 035720, corp_code 00258801
dart_get_company_overview	NAVER	성공	KOSPI, stock_code 035420, corp_code 00266961
dart_get_financial_statement	NAVER	성공	2023년 사업보고서 기준, 주요 6개 계정 반환
dart_get_company_overview	알테오젠	성공	KOSDAQ GLOBAL, stock_code 196170, corp_code 00989619
dart_get_company_overview	없는회사	정상 실패	INVALID_INPUT

현대차와 알테오젠은 기존 하드코딩 fallback 종목이 아닙니다. 두 종목의 조회 성공을 통해 stock_data_ko.json 기반 종목명 검색과 OpenDART corpCode.xml 기반 stockCode → corpCode 매핑이 하드코딩되지 않은 상장사에도 실제로 동작함을 확인했습니다.

또한 현대차 재무제표 테스트에서 net_income이 정상 반환되었습니다. 이를 통해 DART 계정명 alias matching 개선이 실제 로컬 API 테스트에서도 동작함을 확인했습니다.

제한사항: 현재 영문 종목명 매칭은 보수적으로 동작합니다. NAVER는 조회되지만, naver 또는 Naver처럼 소문자/혼합 대소문자 입력은 아직 조회되지 않을 수 있습니다. 영문 종목명 대소문자 normalize는 후속 PR에서 개선할 예정입니다.

Scripts

npm.cmd run dev
npm.cmd run check
npm.cmd run test
npm.cmd run build
npm.cmd run typecheck