Content
# korea-stock-mcp
A Node.js-based server that exposes Naver Finance data through MCP (Model Context Protocol).
It allows MCP clients like Claude Desktop and Cursor to directly query Korean ETF/theme/market cap/dividend/individual stock prices.
## Tool List
1. **get_etfs_by_market_cap**
- `https://finance.naver.com/sise/etf.naver`
- Retrieves a list of ETFs in order of market capitalization.
- Input
- `limit` (number, optional, default 50): Maximum number of results
- Output
- `items[]`: `{ name, code, currentPrice, nav, changeRate }`
2. **get_themes_with_leaders**
- `https://finance.naver.com/sise/theme.naver`
- Retrieves themes in order of high increase compared to the previous day and returns the leading stocks for each theme.
- Input
- `limit` (number, optional, default 50)
- Output
- `items[]`: `{ themeName, themeId, changeRate, leaders[] }`
3. **get_market_cap_stocks**
- `https://finance.naver.com/sise/sise_market_sum.naver`
- Retrieves stock names and current prices in order of market capitalization.
- Input
- `sosok` (number, optional): 0=KOSPI, 1=KOSDAQ (default 0)
- `page` (number, optional, default 1)
- `limit` (number, optional, default 50)
- Output
- `items[]`: `{ name, code, currentPrice }`
4. **get_dividend_yield_stocks**
- `https://finance.naver.com/sise/dividend_list.naver`
- Retrieves stock information in order of high dividend yield.
- Input
- `page` (number, optional, default 1)
- `limit` (number, optional, default 50)
- Output
- `items[]`: `{ name, code, currentPrice, dividend, dividendYield }`
5. **search_stock_code**
- `https://finance.naver.com/search/search.naver?query={stock_name}`
- Searches for a stock code by stock name.
- Input
- `query` (string): Stock name (e.g., `"Samsung Electronics"`)
- Output
- `result`: `{ name, code }` or `null`
6. **get_stock_price_by_code**
- `https://finance.naver.com/item/main.naver?code={stock_code}`
- Retrieves current price information by stock code.
- Input
- `code` (string): 6-digit stock code (e.g., `"005930"`)
- Output
- `{ name, code, currentPrice }`
> All tools return results in JSON format in `structuredContent` and pretty-printed JSON strings in `content[0].text`. MCP clients can use either format.
## Installation and Execution
### 1) For Local Development
```bash
# Initialize project
npm install
# Run MCP server (STDIO)
node index.js
```
or
```bash
npm start
```
### 2) Execute with npx
If the package is distributed on npm, it can be executed in another environment as follows:
```bash
npx korea-stock-mcp
```
(When testing locally, you can create a global link with `npm link` and then execute it with `npx korea-stock-mcp` or `korea-stock-mcp`.)
## Example of Integration with Claude Desktop
- Modify the `claude_desktop_config.json` file.
```
{
"mcpServers": {
"korea-stock-mcp": {
"command": "npx",
"args": ["-y", "@drfirst/korea-stock-mcp@latest"]
}
}
}
```
## Example Usage
Example prompts:
> Use korea-stock-mcp to query today's major themes and corresponding theme stocks
> Use korea-stock-mcp to query today's ETF information
> Use korea-stock-mcp to query stock listings in order of market capitalization today
> Use korea-stock-mcp to check the current price of TLVB