Korea Stock Analyzer MCP Server KOSPI KOSDAQ

Overview

This MCP (Model Context Protocol) server analyzes South Korean equities listed on KOSPI and KOSDAQ using six well-known stock-picking strategies: Buffett, Lynch, Graham, Greenblatt and Fisher and Templeton. It packages each strategy as an MCP-compatible tool so language models and developer apps can query structured analysis and screening results programmatically. The server is useful for building screener UIs, automations (alerts, portfolio rebalancing), or feeding strategy-informed signals into larger decision systems.

Designed for developers, the server provides data ingestion, per-strategy scoring, and an HTTP/MCP interface that returns normalized JSON results for each ticker. This makes it straightforward to integrate the analyses into notebooks, web backends, or chat assistants that rely on the MCP for tool invocation.

Features

• Strategy implementations: Buffett, Lynch, Graham, Greenblatt, Fisher, Templeton
• Dual-market support: KOSPI and KOSDAQ
• MCP-compatible tool metadata and endpoints for model-driven orchestration
• Stock-level scoring and ranked lists per strategy
• Configurable data source (local CSV, public APIs) and update scheduling
• Docker-friendly deployment and simple CLI for local testing
• JSON output schema suitable for downstream automation

Installation / Configuration

Clone the repository, install dependencies, and run the server. Example assumes Python 3.9+.

Clone and install:

git clone https://github.com/Mrbaeksang/korea-stock-analyzer-mcp.git
cd korea-stock-analyzer-mcp
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Environment variables (example):

export MCP_PORT=8080
export DATA_SOURCE=api    # options: api | csv
export API_KEY=your_api_key_here
export DB_PATH=./data/db.sqlite

Run locally:

python -m server.main --port $MCP_PORT

Run with Docker:

docker build -t korea-stock-analyzer .
docker run -p 8080:8080 \
  -e DATA_SOURCE=api \
  -e API_KEY=your_api_key_here \
  korea-stock-analyzer

Configuration file (config.yml example):

server:
  host: 0.0.0.0
  port: 8080

data:
  source: api
  api_key: "REPLACE_WITH_KEY"
  update_interval_minutes: 60

mcp:
  enable: true
  tools_path: /mcp/tools

Available Resources

The server exposes an MCP-style tool registry and REST endpoints. Key endpoints:

Sample /analyze request:

curl -X POST http://localhost:8080/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "tickers": ["005930.KS", "035720.KS"],
    "strategy": "Graham",
    "market": "KOSPI"
  }'

Sample response (trimmed):

{
  "results": [
    {
      "ticker": "005930.KS",
      "name": "Samsung Electronics",
      "market": "KOSPI",
      "strategy": "Graham",
      "score": 78.4,
      "metrics": {
        "pe": 12.5,
        "pb": 1.6,
        "eps_growth_3y": 8.2
      },
      "recommendation": "Consider"
    }
  ]
}

Output schema (summary):

Use Cases

• Strategy-driven screener
  • Request /rankings?strategy=Buffett&market=KOSPI to get Buffett-style value candidates, then render a UI table sorted by score.
• Automated alerts
  • Poll /analyze for a watchlist every hour and trigger notifications when recommendation changes to “Buy”.
• Model orchestration
  • Use the /mcp/tools endpoint to let an LLM discover and call the proper strategy tool via MCP; the tool returns structured JSON the model can reason with.
• Research and backtesting
  • Export ranked lists to CSV and feed into a backtest engine to evaluate strategy returns over historical windows.
• Portfolio construction
  • Combine scores from multiple strategies (ensemble) by calling /analyze for the same tickers with different strategies and computing a weighted average.

Concrete example — check top 5 Graham picks on KOSDAQ:

curl "http://localhost:8080/rankings?strategy=Graham&market=KOSDAQ&limit=5"

You can then ingest this JSON into a plotting library or spreadsheet for further analysis.

Notes for Developers

• Strategy logic is implemented in modular handlers under the strategies/ directory to simplify customization or adding new criteria.
• Data ingestion supports CSV import for offline/backfill workflows: drop a CSV into data/imports/ and run the provided loader script.
• The MCP metadata endpoint follows a predictable JSON structure so LLMs and other orchestration layers can dynamically discover available tools and call them safely.
• Security: when exposing the server publicly, set proper CORS, API auth, and rate limits. Use HTTPS in production.

For implementation details, code layout, and contribution guidelines, refer to the repository README and the source under the strategies/ and server/ folders.