Crawls Korean stock market data from Naver Finance, providing tools to fetch top searched stocks and detailed stock information by code, including prices, change rates, trading volume, and market capitalization.
MCP (Model Context Protocol) server for crawling Korean stock market data from Naver Finance.
A Node.js-based web crawler built with TypeScript, Axios, and Cheerio, with MCP server support for AI assistants.
crawl-top-stocks: Fetch the most searched stocks from Naver Finance with real-time data
crawl-stock-detail: Get comprehensive stock information by 6-digit stock code
MCP Server Support: Full integration with AI assistants via Model Context Protocol
HTTP & STDIO Transports: Flexible transport options for different use cases
Korean Encoding Support: Proper handling of Korean characters (EUC-KR)
TypeScript Support: Fully typed with strict mode enabled
Modular Architecture: Extensible base crawler class for custom implementations
HTML Parsing: Cheerio-based HTML parsing with helper utilities
HTTP Requests: Axios-based HTTP client with retry logic
Testing: Vitest with unit, integration, and E2E tests
Code Quality: ESLint and Prettier for code consistency
Related MCP server: kospi-kosdaq-stock-server
src/
├── crawlers/ # Crawler implementations
│ ├── baseCrawler.ts # Base class for all crawlers
│ ├── exampleCrawler.ts # Example crawler implementation
│ └── index.ts
├── utils/ # Utility functions
│ ├── request.ts # HTTP client with retry logic
│ ├── parser.ts # HTML parsing helper
│ └── index.ts
├── types/ # TypeScript type definitions
│ └── index.ts
└── index.ts # Main entry point
tests/
├── unit/ # Unit tests
├── integration/ # Integration tests
└── e2e/ # E2E testsnpm install -g naver-finance-crawl-mcpTo install Naver Finance Crawl MCP Server for any client automatically via Smithery:
npx -y @smithery/cli@latest install naver-finance-crawl-mcp --client <CLIENT_NAME>Available clients: cursor, claude, vscode, windsurf, cline, zed, etc.
Example for Cursor:
npx -y @smithery/cli@latest install naver-finance-crawl-mcp --client cursorThis will automatically configure the MCP server in your chosen client.
pnpm installNaver Finance Crawl MCP can be integrated with various AI coding assistants and IDEs that support the Model Context Protocol (MCP).
Node.js >= v18.0.0
An MCP-compatible client (Cursor, Claude Code, VS Code, Windsurf, etc.)
Go to: Settings -> Cursor Settings -> MCP -> Add new global MCP server
Add the following configuration to your ~/.cursor/mcp.json file:
{
"mcpServers": {
"naver-finance": {
"command": "npx",
"args": ["-y", "naver-finance-crawl-mcp"]
}
}
}With HTTP transport:
{
"mcpServers": {
"naver-finance": {
"command": "npx",
"args": ["-y", "naver-finance-crawl-mcp", "--transport", "http", "--port", "5000"]
}
}
}Run this command:
claude mcp add naver-finance -- npx -y naver-finance-crawl-mcpOr with HTTP transport:
claude mcp add naver-finance -- npx -y naver-finance-crawl-mcp --transport http --port 5000Add this to your VS Code MCP config file. See VS Code MCP docs for more info.
"mcp": {
"servers": {
"naver-finance": {
"type": "stdio",
"command": "npx",
"args": ["-y", "naver-finance-crawl-mcp"]
}
}
}Add this to your Windsurf MCP config file:
{
"mcpServers": {
"naver-finance": {
"command": "npx",
"args": ["-y", "naver-finance-crawl-mcp"]
}
}
}Open Cline
Click the hamburger menu icon (☰) to enter the MCP Servers section
Choose Remote Servers tab
Click the Edit Configuration button
Add naver-finance to mcpServers:
{
"mcpServers": {
"naver-finance": {
"command": "npx",
"args": ["-y", "naver-finance-crawl-mcp"]
}
}
}Open Claude Desktop developer settings and edit your claude_desktop_config.json file:
{
"mcpServers": {
"naver-finance": {
"command": "npx",
"args": ["-y", "naver-finance-crawl-mcp"]
}
}
}Add this to your Zed settings.json:
{
"context_servers": {
"naver-finance": {
"source": "custom",
"command": "npx",
"args": ["-y", "naver-finance-crawl-mcp"]
}
}
}Add this to your Roo Code MCP configuration file:
{
"mcpServers": {
"naver-finance": {
"command": "npx",
"args": ["-y", "naver-finance-crawl-mcp"]
}
}
}{
"mcpServers": {
"naver-finance": {
"command": "bunx",
"args": ["-y", "naver-finance-crawl-mcp"]
}
}
}# Type check
pnpm typecheck
# Lint code
pnpm lint
pnpm lint:fix
# Run tests
pnpm test
pnpm test:ui # UI mode
pnpm test:coverage # With coverage report
# Build project
pnpm build
# Watch mode
pnpm dev
# Start MCP server (STDIO transport)
pnpm start
# Start MCP server (HTTP transport)
pnpm start --transport http --port 5000
# Start HTTP REST API server
pnpm start:httpSTDIO Transport (default):
naver-finance-crawl-mcpHTTP Transport:
naver-finance-crawl-mcp --transport http --port 5000The server provides two MCP tools that can be used by LLMs:
crawl_top_stocks: Fetches the most searched stocks from Naver Finance
crawl_stock_detail: Fetches detailed information for a specific stock by its 6-digit code
Naver Finance Crawl MCP provides the following tools that can be used by LLMs:
Crawl top searched stocks from Naver Finance. Returns a list of the most searched stocks with their codes, names, current prices, and change rates.
Parameters: None
Example Response:
{
"success": true,
"count": 10,
"data": [
{
"code": "005930",
"name": "삼성전자",
"currentPrice": "71,000",
"changeRate": "+2.50%"
}
],
"timestamp": "2025-01-29T12:00:00.000Z"
}Crawl detailed information for a specific stock by its 6-digit code. Returns comprehensive data including company info, stock prices, trading volume, and financial metrics.
Parameters:
stockCode (string, required): 6-digit stock code (e.g., "005930" for Samsung Electronics)
Example Request:
{
"stockCode": "005930"
}Example Response:
{
"success": true,
"stockCode": "005930",
"data": {
"companyName": "삼성전자",
"currentPrice": "71,000",
"changeRate": "+2.50%",
"tradingVolume": "1,234,567",
"marketCap": "423조원"
},
"metadata": {
"url": "https://finance.naver.com/item/main.naver?code=005930",
"statusCode": 200,
"timestamp": "2025-01-29T12:00:00.000Z"
}
}In Cursor/Claude Code:
Get the top searched stocks from Naver FinanceThe tool will return:
List of most searched stocks
Stock codes, names, current prices
Price change rates
Timestamp of the data
In Cursor/Claude Code:
Get detailed information for Samsung Electronics (stock code: 005930)The tool will return:
Company name and stock code
Current price and change rate
Trading volume
Market capitalization
Additional financial metrics
In Cursor/Claude Code:
First, show me the top searched stocks.
Then, fetch detailed information for the top 3 stocks.
Analyze which stocks show the most significant price changes.You can also use the crawlers directly in your Node.js applications:
import { ExampleCrawler } from './src/crawlers/exampleCrawler.js';
const crawler = new ExampleCrawler({
timeout: 10000,
retries: 3,
});
const result = await crawler.crawl('https://example.com');
console.log(result);import { BaseCrawler } from './src/crawlers/baseCrawler.js';
import { CrawlResult } from './src/types/index.js';
class MyCrawler extends BaseCrawler {
async crawl(url: string): Promise<CrawlResult> {
const html = await this.fetchHtml(url);
const parser = this.parseHtml(html);
const data = parser.parseStructure('div.item', {
title: 'h2',
price: 'span.price',
});
return {
url,
data,
timestamp: new Date(),
statusCode: 200,
};
}
}import { HtmlParser } from './src/utils/parser.js';
const html = '<h1>Hello</h1><p>World</p>';
const parser = new HtmlParser(html);
// Get text from elements
const title = parser.getFirstText('h1');
console.log(title); // "Hello"
// Get attributes
const links = parser.getAttributes('a[href]', 'href');
// Parse structured data
const items = parser.parseStructure('div.item', {
name: 'h2',
description: 'p',
});tsconfig.json: TypeScript compiler options
vitest.config.ts: Vitest test runner configuration
.eslintrc.json: ESLint rules configuration
.prettierrc.json: Prettier formatting rules
axios: HTTP client library
cheerio: jQuery-like HTML parsing
typescript: TypeScript compiler
vitest: Unit testing framework
@typescript-eslint/*: TypeScript linting
eslint: Code linting
prettier: Code formatting
tsx: TypeScript executor
The project includes comprehensive tests covering:
Unit tests for utilities and base classes
Integration tests for crawler functionality
E2E tests for complete workflows
Run tests with:
pnpm test # Run all tests
pnpm test:ui # Interactive UI
pnpm test:coverage # With coverage reportdocker build -t naver-finance-crawl-mcp .With STDIO transport:
docker run -i --rm naver-finance-crawl-mcpWith HTTP transport:
docker run -d -p 5000:5000 \
--name naver-finance \
naver-finance-crawl-mcp \
node dist/mcp-server.js --transport http --port 5000Create a docker-compose.yml:
version: '3.8'
services:
naver-finance-crawl-mcp:
build: .
ports:
- "5000:5000"
environment:
- PORT=5000
- NODE_ENV=production
command: ["node", "dist/mcp-server.js", "--transport", "http", "--port", "5000"]
restart: unless-stopped
healthcheck:
test: ["CMD", "node", "-e", "require('http').get('http://localhost:5000/mcp', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"]
interval: 30s
timeout: 3s
retries: 3
start_period: 5sRun with Docker Compose:
docker-compose up -dConfigure your MCP client to use the Docker container:
{
"mcpServers": {
"naver-finance": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"naver-finance-crawl-mcp"
]
}
}
}The project follows a modular architecture:
crawlers/: Crawler implementations
baseCrawler.ts: Base class for all crawlers
naverFinanceCrawler.ts: Naver Finance stock detail crawler
TopStocksCrawler.ts: Top searched stocks crawler
exampleCrawler.ts: Example crawler implementation
tools/: MCP tool implementations
crawl-top-stocks.ts: MCP tool for top stocks
crawl-stock-detail.ts: MCP tool for stock details
utils/: Utility functions
request.ts: HTTP client with retry logic
parser.ts: HTML parsing helpers
types/: TypeScript type definitions
mcp-server.ts: MCP server entry point (STDIO/HTTP)
http-server.ts: REST API server entry point
Contributions are welcome! Please feel free to submit a Pull Request.
greatsumini
MIT
Crawl detailed information for a specific stock by its 6-digit code. Returns comprehensive data including company info, stock prices, trading volume, and financial metrics.
| Name | Required | Description | Default |
|---|---|---|---|
| stockCode | Yes | 6-digit stock code (e.g., "005930" for Samsung Electronics) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. While it mentions the tool 'returns comprehensive data,' it lacks behavioral details such as rate limits, authentication requirements, data freshness, error handling, or whether this is a read-only operation. For a data-fetching tool with zero annotation coverage, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with zero waste. The first sentence states the purpose and parameter, and the second sentence details the return data, making it front-loaded and efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (single parameter, no output schema, no annotations), the description is adequate but incomplete. It covers purpose and return data types but lacks behavioral context and output structure details, which are important for a crawling tool without annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the schema fully documenting the 'stockCode' parameter's type, pattern, and example. The description adds minimal value beyond the schema by mentioning '6-digit code' and implying it identifies a stock, but doesn't provide additional syntax or format details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('crawl detailed information'), target resource ('for a specific stock'), and key identifier ('by its 6-digit code'). It distinguishes from the sibling tool 'crawl_top_stocks' by focusing on individual stock details rather than top stocks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by specifying 'for a specific stock by its 6-digit code,' which suggests when to use this tool. However, it doesn't explicitly mention when not to use it or provide alternatives beyond the implied distinction from 'crawl_top_stocks.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Crawl top searched stocks from Naver Finance. Returns a list of the most searched stocks with their codes, names, current prices, and change rates.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the tool's behavior as a data retrieval operation ('Crawl... Returns a list') but lacks details about rate limits, authentication needs, data freshness, or potential side effects. The description doesn't contradict annotations since none exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise with two sentences: the first states the action and source, the second specifies the return format. Every word adds value with zero wasted text, and information is front-loaded appropriately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no annotations and no output schema, the description provides adequate context about what data is retrieved and from where. However, it lacks information about output structure details (e.g., list format, data types) that would be helpful given the absence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately focuses on output semantics rather than input parameters, establishing a baseline score of 4 for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Crawl top searched stocks'), resource ('from Naver Finance'), and output format ('list of the most searched stocks with their codes, names, current prices, and change rates'). It distinguishes from the sibling tool 'crawl_stock_detail' by focusing on aggregated top stocks rather than individual stock details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly suggests usage when needing aggregated top stock data rather than detailed individual stock information (contrasting with 'crawl_stock_detail'). However, it lacks explicit guidance on when not to use this tool or alternative scenarios beyond the sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The two tools have clearly distinct purposes: crawl_stock_detail focuses on retrieving detailed information for a specific stock by its code, while crawl_top_stocks retrieves a list of top searched stocks. There is no overlap or ambiguity between these functions, making it easy for an agent to select the appropriate tool.
Both tool names follow a consistent verb_noun pattern with 'crawl_' as the prefix, followed by descriptive nouns (stock_detail and top_stocks). This uniformity enhances readability and predictability, adhering to a clear naming convention throughout the set.
With only 2 tools, the server feels thin for a finance crawling domain, as it lacks operations for broader data retrieval, such as market indices, sector analysis, or historical data. While the tools are well-defined, the limited count may restrict agent capabilities in handling more complex financial queries.
The tool set is significantly incomplete for a finance crawling server. It covers specific stock details and top searches but misses essential operations like crawling market summaries, financial news, historical price data, or sector performance. These gaps will likely cause agent failures when broader financial information is needed.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Search company disclosures and financial statements from the Korean market. Retrieve stock profile…
Korean market data for AI agents: K-beauty/K-food products, Naver trends, stocks, real estate.
Scrape stock quotes, historical prices, and financial statements from Yahoo Finance.
Korean + US market data for AI agents: DART, Korean prices/screeners, SEC EDGAR, 13F. Free tier.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/greatSumini/naver-finance-crawl-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server