MCP Stock Details Server

A comprehensive Model Context Protocol (MCP) server for Korean stock market analysis, providing detailed financial data, analysis tools, and investment insights.

🚀 Features

Phase 1 ✅ - Core Infrastructure

• MCP Server Framework: Model Context Protocol compliant server
• Data Collection: DART (Data Analysis, Retrieval and Transfer System) integration
• Caching System: Redis-based caching with memory fallback
• Error Handling: Comprehensive exception handling and logging

Phase 2 ✅ - Analysis Tools (Weeks 1-5)

Week 1: Company & Financial Analysis

• get_company_overview: Comprehensive company information
• get_financial_statements: Income statement, balance sheet, cash flow analysis

Week 2: Financial Ratios & Valuation

• get_financial_ratios: 50+ financial ratios with industry benchmarks
• get_valuation_metrics: Multiple valuation approaches (DCF, multiples, etc.)

Week 3: ESG & Technical Analysis

• get_esg_info: Environmental, Social, Governance analysis
• get_technical_indicators: Technical analysis indicators (RSI, MACD, etc.)

Week 4: Shareholder & Business Analysis

• get_shareholder_info: Shareholder structure, governance metrics
• get_business_segments: Business segment performance analysis

Week 5: Market Analysis

• get_peer_comparison: Industry peer comparison and benchmarking
• get_analyst_consensus: Analyst consensus, target prices, investment opinions

Upcoming Features (Phase 3-5)

• Advanced valuation models (DCF, Monte Carlo simulation)
• Risk analysis engine (VaR, stress testing)
• Real-time data pipeline
• Performance optimization
• Production deployment

🛠️ Installation

Prerequisites

• Python 3.8 or higher
• Redis (optional, for enhanced caching)

Setup

# Clone the repository
git clone https://github.com/yourusername/mcp-stock-details.git
cd mcp-stock-details

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set up environment variables
cp .env.example .env
# Edit .env with your DART API key and other settings

Environment Variables

# Required
DART_API_KEY=your_dart_api_key_here

# Optional
REDIS_URL=redis://localhost:6379/0
LOG_LEVEL=INFO
CACHE_TTL=3600

🚀 Quick Start

Running the Server

# Start the MCP server
python -m src.server

# Or run with specific configuration
python -m src.server --config config/development.json

Using with Claude Desktop

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "stock-details": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/mcp-stock-details",
      "env": {
        "DART_API_KEY": "your_api_key"
      }
    }
  }
}

Example Usage

# Get company overview
result = await server.call_tool("get_company_overview", {
    "company_code": "005930",  # Samsung Electronics
    "include_financial_summary": True
})

# Analyze financial ratios
result = await server.call_tool("get_financial_ratios", {
    "company_code": "005930",
    "include_industry_comparison": True,
    "analysis_period": "3Y"
})

# Compare with peers
result = await server.call_tool("get_peer_comparison", {
    "company_code": "005930",
    "include_valuation_comparison": True,
    "max_peers": 5
})

📊 Supported Analysis

Financial Analysis

• Profitability Ratios: ROE, ROA, Operating Margin, Net Margin
• Liquidity Ratios: Current Ratio, Quick Ratio, Cash Ratio
• Leverage Ratios: Debt-to-Equity, Interest Coverage, EBITDA Coverage
• Efficiency Ratios: Asset Turnover, Inventory Turnover, Receivables Turnover
• Valuation Ratios: P/E, P/B, EV/EBITDA, PEG Ratio

Advanced Analysis

• DCF Valuation: Multi-stage dividend discount model
• Peer Comparison: Industry benchmarking and relative valuation
• ESG Scoring: Environmental, Social, Governance metrics
• Technical Indicators: RSI, MACD, Bollinger Bands, Moving Averages
• Risk Analysis: Beta, VaR, Sharpe Ratio, Maximum Drawdown

Market Intelligence

• Analyst Consensus: Target prices, investment ratings, earnings estimates
• Shareholder Analysis: Ownership structure, governance metrics
• Business Segments: Revenue breakdown, segment performance analysis

🧪 Testing

# Run all tests
python -m pytest

# Run with coverage
python -m pytest --cov=src --cov-report=html

# Run specific test categories
python -m pytest tests/unit/
python -m pytest tests/integration/

📁 Project Structure

mcp-stock-details/
├── src/
│   ├── server.py                 # Main MCP server
│   ├── config.py                 # Configuration management
│   ├── exceptions.py             # Custom exceptions
│   ├── models/                   # Data models
│   ├── tools/                    # Analysis tools
│   │   ├── company_tools.py
│   │   ├── financial_tools.py
│   │   ├── valuation_tools.py
│   │   ├── esg_tools.py
│   │   ├── technical_tools.py
│   │   ├── risk_tools.py
│   │   ├── shareholder_tools.py
│   │   ├── business_segment_tools.py
│   │   ├── peer_comparison_tools.py
│   │   └── analyst_consensus_tools.py
│   ├── collectors/               # Data collectors
│   ├── utils/                    # Utility functions
│   └── cache/                    # Caching system
├── tests/
│   ├── unit/                     # Unit tests
│   ├── integration/              # Integration tests
│   └── fixtures/                 # Test data
├── config/                       # Configuration files
├── docs/                         # Documentation
├── requirements.txt
├── development-plan.md
└── README.md

📈 Development Status

• [x] Phase 1: Core Infrastructure (Completed)
• [x] Phase 2: Analysis Tools - Weeks 1-5 (Completed)
• [ ] Phase 3: Advanced Analysis Engine - Weeks 6-8
• [ ] Phase 4: Performance & Quality - Weeks 9-10
• [ ] Phase 5: Deployment & Operations - Weeks 11-12

See Development Plan for detailed roadmap.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Install development dependencies
pip install -r requirements-dev.txt

# Install pre-commit hooks
pre-commit install

# Run tests before committing
python -m pytest

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Related Resources

• Model Context Protocol (MCP)
• DART Open API
• Korean Stock Market Data

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: support@example.com

🙏 Acknowledgments

• DART (금융감독원) for providing comprehensive financial data
• Model Context Protocol team for the excellent framework
• Korean financial data providers and community

---

Note: This project is for educational and research purposes. Please ensure compliance with data usage terms and local regulations when using financial data.