A
securityA
licenseA
qualityA Model Context Protocol server for interacting with Korea Investment & Securities (KIS) REST API, enabling domestic and foreign stock trading, price checks, and account management.
Last updated -
10
8
MIT License
Integrates with DART (Data Analysis, Retrieval and Transfer System) to collect and analyze Korean financial market data, enabling comprehensive stock analysis and financial reporting
Uses .env files for configuration management of API keys, service endpoints, and other environment variables
Offers GitHub Issues and Discussions integration for project support and community engagement
Connects to Korean Stock Market Data through Naver Finance to provide market intelligence and stock information
Implements pre-commit hooks for code quality assurance and consistent development practices
Incorporates pytest for comprehensive testing of the server's functionality and data analysis capabilities
Implements Redis-based caching system for improved performance when retrieving financial data and analysis results
Provides detailed analysis capabilities for Samsung Electronics (company code 005930) and other Korean companies with financial metrics and comparative analysis
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 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
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.
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
A Model Context Protocol server providing comprehensive Korean stock market analysis, including financial data, valuation metrics, ESG information, and investment insights.
Related MCP Servers
- AsecurityAlicenseAqualityA Model Context Protocol server providing tools for querying A-share stock market data, including historical prices, financial reports, market indices, and macroeconomic indicators.Last updated -27431MIT License
- AsecurityAlicenseAqualityA Model Context Protocol server focused on China's A-share stock market that provides data on stocks, financials, market indices, and macroeconomic indicators.Last updated -27431MIT License
- -securityFlicense-qualityA custom Model Context Protocol server that provides real-time financial analysis tools including stock monitoring, portfolio management, market summaries, and automated price alerts with Telegram notifications.Last updated -