Naver Finance Crawler

A Model Context Protocol (MCP) server for crawling Korean stock and company information from Naver Finance. Supports both HTTP and stdio transports, making it perfect for integration with Claude and other AI tools.

Features

• 🏢 Company Information Crawling: Get detailed company info by stock code
• 📈 Popular Stocks: Crawl top performing stocks from KOSPI/KOSDAQ
• 🌐 Multiple Transports: Support for both stdio and HTTP transports
• 🇰🇷 Korean Support: Proper handling of Korean character encoding
• 🔧 CLI Interface: Easy-to-use command line interface
• 🚀 MCP Compatible: Works seamlessly with Claude and other MCP clients

Installation

npm install -g naver-finance-crawler

Usage

As an MCP Server

Stdio Transport (Default)

naver-finance-crawler
# or
naver-finance-crawler --transport stdio

HTTP Transport

naver-finance-crawler --transport http --port 5000

Available Tools

1. crawl_company

Crawl individual company information by stock code.

Parameters:

• stockCode (string): 6-digit Korean stock code (e.g., "005930" for Samsung Electronics)

Example:

{
  "name": "crawl_company",
  "arguments": {
    "stockCode": "005930"
  }
}

2. crawl_popular_stocks

Crawl popular (top low-up) stocks with company information.

Parameters:

• sosok (string, optional): Market type
  • "0": KOSPI (default)
  • "1": KOSDAQ

Example:

{
  "name": "crawl_popular_stocks", 
  "arguments": {
    "sosok": "0"
  }
}

Integration with AI Tools

⚠️ Prerequisites: Before configuring any IDE integration, make sure to install the package globally:

npm install -g naver-finance-crawler

Claude Desktop

Add this to your Claude Desktop MCP settings (claude_desktop_config.json):

Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "naver-finance": {
      "command": "naver-finance-crawler",
      "args": ["--transport", "stdio"]
    }
  }
}

Cursor IDE

1. Install the MCP extension for Cursor
2. Add server configuration in your workspace settings (.cursor/mcp.json):

{
  "mcpServers": {
    "naver-finance": {
      "command": "naver-finance-crawler",
      "args": ["--transport", "stdio"],
      "env": {}
    }
  }
}

3. Restart Cursor to load the MCP server

Zed Editor

Add to your Zed settings (~/.config/zed/settings.json):

{
  "experimental": {
    "mcp": {
      "servers": {
        "naver-finance": {
          "command": "naver-finance-crawler",
          "args": ["--transport", "stdio"]
        }
      }
    }
  }
}

Continue.dev (VS Code Extension)

1. Install Continue.dev extension in VS Code
2. Configure MCP server in Continue config (~/.continue/config.json):

{
  "mcp": {
    "servers": {
      "naver-finance": {
        "command": "naver-finance-crawler",
        "args": ["--transport", "stdio"]
      }
    }
  }
}

Custom Integration (Any MCP Client)

Stdio Transport

# Start the server
naver-finance-crawler --transport stdio

# Send JSON-RPC requests via stdin
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | naver-finance-crawler

HTTP Transport

# Start HTTP server
naver-finance-crawler --transport http --port 5000

# Make HTTP requests
curl -X POST http://localhost:5000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}'

Aider (AI Pair Programming)

# Use with Aider CLI
aider --mcp-server naver-finance-crawler

Windsurf IDE (Codeium)

1. Open Windsurf IDE settings
2. Navigate to Extensions → MCP
3. Add new MCP server:
   • Name: naver-finance
   • Command: naver-finance-crawler
   • Args: ["--transport", "stdio"]

Replit Agent

Add to your Replit configuration (.replit):

[mcp]
  [mcp.servers.naver-finance]
  command = "naver-finance-crawler"
  args = ["--transport", "stdio"]

Bolt.new / StackBlitz

In your project settings, add MCP server configuration:

{
  "mcp": {
    "servers": {
      "naver-finance": {
        "command": "npx",
        "args": ["naver-finance-crawler", "--transport", "stdio"]
      }
    }
  }
}

Sourcegraph Cody

Add to Cody extension settings (cody.json):

{
  "mcp": {
    "servers": {
      "naver-finance": {
        "command": "naver-finance-crawler",
        "args": ["--transport", "stdio"]
      }
    }
  }
}

TabNine

Configure in TabNine settings:

{
  "mcp_servers": [
    {
      "name": "naver-finance",
      "command": "naver-finance-crawler",
      "args": ["--transport", "stdio"]
    }
  ]
}

Custom Integrations

Docker Container

FROM node:18-alpine
RUN npm install -g naver-finance-crawler
EXPOSE 5000
CMD ["naver-finance-crawler", "--transport", "http", "--port", "5000"]

# Build and run
docker build -t naver-finance-mcp .
docker run -p 5000:5000 naver-finance-mcp

Systemd Service (Linux)

# /etc/systemd/system/naver-finance-mcp.service
[Unit]
Description=Naver Finance MCP Server
After=network.target

[Service]
Type=simple
User=nodejs
ExecStart=/usr/bin/naver-finance-crawler --transport http --port 5000
Restart=always
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

# Enable and start service
sudo systemctl enable naver-finance-mcp
sudo systemctl start naver-finance-mcp

MCP Client Libraries

Python

from mcp import Client
import subprocess

# Start MCP server process
process = subprocess.Popen(
    ["naver-finance-crawler", "--transport", "stdio"],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    stderr=subprocess.PIPE
)

client = Client(process.stdin, process.stdout)
result = await client.call_tool("crawl_company", {"stockCode": "005930"})

Node.js

import { spawn } from 'child_process';
import { McpClient } from '@modelcontextprotocol/client';

const serverProcess = spawn('naver-finance-crawler', ['--transport', 'stdio']);
const client = new McpClient(serverProcess.stdin, serverProcess.stdout);

const result = await client.callTool('crawl_company', { stockCode: '005930' });

HTTP API Usage

When running in HTTP mode, the server exposes an endpoint at /mcp:

curl -X POST http://localhost:5000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "crawl_company",
      "arguments": {
        "stockCode": "005930"
      }
    }
  }'

Response Format

All responses include Korean text properly encoded and null values converted to 0 for consistency.

Company Information Response

{
  "success": true,
  "data": {
    "companyName": "삼성전자",
    "stockCode": "005930", 
    "market": "KOSPI",
    "businessSummary": "반도체, 디스플레이 패널 등 제조",
    "mainProducts": ["메모리반도체", "시스템LSI"],
    "corporateGovernance": {
      "ceo": "김기남",
      "employees": 267937,
      "establishedDate": "1969-01-13",
      "headquarters": "경기도 수원시"
    },
    "financialHighlights": {
      "revenue": 279680000000000,
      "operatingProfit": 42186000000000,
      "netProfit": 26951000000000,
      "totalAssets": 427988000000000
    },
    "crawledAt": "2025-10-31T10:30:00.000Z"
  }
}

Popular Stocks Response

{
  "success": true,
  "data": [
    {
      "rank": 1,
      "name": "삼성전자",
      "code": "005930",
      "currentPrice": 71500,
      "changeAmount": 1200,
      "changePercent": 1.71,
      "companyInfo": {
        "companyName": "삼성전자",
        "businessSummary": "...",
        "..."
      }
    }
  ],
  "summary": {
    "total": 50,
    "withCompanyInfo": 50,
    "withoutCompanyInfo": 0
  }
}

CLI Options

• --transport <stdio|http>: Transport type (default: stdio)
• --port <number>: Port for HTTP transport (default: 5000)

Development

# Clone repository
git clone https://github.com/dasanworld/NaverFinnaceCrawal.git
cd NaverFinnaceCrawal

# Install dependencies
pnpm install

# Development mode
pnpm dev:mcp

# Build
pnpm build

# Run tests
pnpm test

Architecture

• MCP Server: Built using @modelcontextprotocol/sdk
• HTTP Client: Axios with proper Korean encoding (EUC-KR → UTF-8)
• HTML Parsing: Cheerio for DOM manipulation
• CLI: Commander.js for argument parsing
• Type Safety: Full TypeScript support

Requirements

• Node.js ≥ 18.0.0
• Compatible with MCP protocol

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support

• GitHub Issues
• Documentation

Made with ❤️ for the Korean fintech community