MCP Stock Details Server
by whdghk1907
README.md
# MCP Stock Details Server
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](tests/)
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
```bash
# 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
```bash
# 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
```bash
# 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:
```json
{
"mcpServers": {
"stock-details": {
"command": "python",
"args": ["-m", "src.server"],
"cwd": "/path/to/mcp-stock-details",
"env": {
"DART_API_KEY": "your_api_key"
}
}
}
}
```
### Example Usage
```python
# 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
```bash
# 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](development-plan.md) for detailed roadmap.
## π€ Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
### Development Setup
```bash
# 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](LICENSE) file for details.
## π Related Resources
- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
- [DART Open API](https://opendart.fss.or.kr/)
- [Korean Stock Market Data](https://finance.naver.com/)
## π Support
- **Issues**: [GitHub Issues](https://github.com/yourusername/mcp-stock-details/issues)
- **Discussions**: [GitHub Discussions](https://github.com/yourusername/mcp-stock-details/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.This server cannot be deployed
Maintenance
ActivityInactive
ResponsivenessNo recent community issues