MCP Stock Details Server

Python 3.8+ License: 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

Related MCP server: KIS REST API MCP Server

🛠️ 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

Phase 1: Core Infrastructure (Completed)
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

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

MCP Stock Details Server

MCP Stock Details Server

🚀 Features

Phase 1 ✅ - Core Infrastructure

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

Week 1: Company & Financial Analysis

Week 2: Financial Ratios & Valuation

Week 3: ESG & Technical Analysis

Week 4: Shareholder & Business Analysis

Week 5: Market Analysis

Upcoming Features (Phase 3-5)

🛠️ Installation

Prerequisites

Setup

Environment Variables

🚀 Quick Start

Running the Server

Using with Claude Desktop

Example Usage

📊 Supported Analysis

Financial Analysis

Advanced Analysis

Market Intelligence

🧪 Testing

📁 Project Structure

📈 Development Status

🤝 Contributing

Development Setup

📄 License

🔗 Related Resources

📞 Support

🙏 Acknowledgments

Related Resources

New MCP Servers

MCP directory API