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
Week 1: Company & Financial Analysis
get_company_overview: Comprehensive company informationget_financial_statements: Income statement, balance sheet, cash flow analysis
Week 2: Financial Ratios & Valuation
get_financial_ratios: 50+ financial ratios with industry benchmarksget_valuation_metrics: Multiple valuation approaches (DCF, multiples, etc.)
Week 3: ESG & Technical Analysis
get_esg_info: Environmental, Social, Governance analysisget_technical_indicators: Technical analysis indicators (RSI, MACD, etc.)
Week 4: Shareholder & Business Analysis
get_shareholder_info: Shareholder structure, governance metricsget_business_segments: Business segment performance analysis
Week 5: Market Analysis
get_peer_comparison: Industry peer comparison and benchmarkingget_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
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.
📞 Support
🙏 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.