MCP Stock Details Server

# 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.