[한국어](README.md) | English
# MCP OpenDART
Model Context Protocol (MCP) server for OpenDART (Korea Financial Supervisory Service's Data Analysis, Retrieval and Transfer System). This integration enables secure, contextual AI interactions with OpenDART while maintaining data privacy and security.
## Example Usage
Ask your AI assistant to:
- **📊 Financial Reports** - "Get the latest quarterly report for Samsung Electronics"
- **🔍 Disclosure Search** - "Find major shareholding changes in KOSPI companies last month"
- **📈 Corporate Analysis** - "Show me the financial statements of Hyundai Motor for the past 3 years"
- **⚡ Real-time Updates** - "Get today's important disclosures for technology sector"
### Feature Demo
#### Usage Example: Samsung Electronics 2024 Annual Report Analysis
**Question**:
Based on Samsung Electronics' 2024 annual report, please answer the following questions:
1. Who are the top earners? Please provide the top 5 individuals by compensation and their amounts.
2. Has there been any change in the owner's shareholding? What are the changes in shareholding ratios and transaction reasons for major shareholders and related parties?
3. How much dividend was paid? Please provide the 3-year trend of dividend amount, dividend yield, and payout ratio, as well as dividend sustainability.
4. Are there any hidden risks? Please search the financial statement notes for information related to lawsuits, contingent liabilities, and provisions.
5. What is the outlook for the HBM business? Please summarize the company's official position on HBM and AI semiconductors from the business content section.
Please summarize 3 key points to watch when investing in Samsung Electronics.
**Answer**:
I will analyze based on Samsung Electronics' 2024 annual report. First, I will look up Samsung Electronics' corporate code. Samsung Electronics' corporate code is 00126380. Now I will retrieve information for each question. Now I will search the financial statement notes for information related to lawsuits and contingent liabilities. Now I will provide a comprehensive analysis based on the collected information.
---
## Comprehensive Analysis of Samsung Electronics 2024 Annual Report
### 1) Top Earners - Top 5 Individuals by Compensation
| Rank | Name | Position | Total Compensation |
|:---:|------|----------|-------------------:|
| **1** | **Kyung Kye-hyun** | Advisor | **8.036 billion KRW** |
| 2 | Lee Jung-bae | Consultant | 6.950 billion KRW |
| 3 | Choi Si-young | Consultant | 6.900 billion KRW |
| 4 | Han Jong-hee | CEO | 5.240 billion KRW |
| 5 | Roh Tae-moon | Director | 5.098 billion KRW |
**Analysis**: It is notable that **retired executives (advisors/consultants) receive higher compensation than current executives**. Former DS Division Head Kyung Kye-hyun received over 8 billion KRW even after retirement, which appears to include severance pay and existing performance bonuses.
---
### 2) Owner Shareholding Changes - Major Shareholders and Related Parties
| Shareholder | Relationship | Beginning Shareholding | Ending Shareholding | Change | Reason |
|-------------|-------------|---------------------:|-------------------:|:------:|--------|
| Samsung Life Insurance | Largest Shareholder | 8.51% | 8.51% | - | No change |
| Samsung C&T | Affiliate | 5.01% | 5.01% | - | No change |
| **Hong Ra-hee** | Related Party | 1.96% | **1.64%** | **▼0.32%** | After-hours trading |
| Lee Jae-yong | Related Party | 1.63% | 1.63% | - | No change |
| **Lee Boo-jin** | Affiliate Executive | 0.93% | **0.80%** | **▼0.13%** | After-hours trading |
| **Lee Seo-hyun** | Affiliate Executive | 0.93% | **0.79%** | **▼0.14%** | After-hours trading |
| **Total** | - | **20.70%** | **20.07%** | **▼0.63%** | - |
**Analysis**:
- **Hong Ra-hee, Lee Boo-jin, and Lee Seo-hyun sold approximately 37 million shares (approximately 2 trillion KRW) through after-hours trading**
- Chairman Lee Jae-yong's shareholding (1.63%) remained unchanged
- Total related party shareholding decreased from 20.70% to 20.07%
- Reason for sale: Estimated to be for inheritance tax payment and portfolio adjustment
---
### 3) Dividend Status - 3-Year Trend
| Item | 2024 | 2023 | 2022 |
|------|-----:|-----:|-----:|
| **Consolidated Net Income** | 33.6 trillion KRW | 14.5 trillion KRW | 54.7 trillion KRW |
| **Total Cash Dividend** | 9.81 trillion KRW | 9.81 trillion KRW | 9.81 trillion KRW |
| **Dividend per Share (Common Stock)** | 1,446 KRW | 1,444 KRW | 1,444 KRW |
| **Dividend Yield (Common Stock)** | 2.7% | 1.9% | 2.5% |
| **Payout Ratio** | 29.2% | 67.8% | 17.9% |
**Dividend Sustainability Assessment**:
- **Positive**: Stable dividend of approximately 9.8 trillion KRW maintained for 3 consecutive years (consistent shareholder return policy)
- **Caution**: 2023 payout ratio of 67.8% was a temporary phenomenon due to sharp decline in net income
- **Outlook**: With 2024 net income recovery (33.6 trillion KRW), payout ratio normalized to 29.2%. Current dividend level is sustainable
---
### 4) Hidden Risks - Financial Statement Notes Analysis
#### 📌 Major Lawsuits/Contingent Liabilities
**① Samsung BioLogics Accounting Treatment Administrative Lawsuit (Ongoing)**
- Financial Services Commission imposed 8 billion KRW fine and ordered financial statement revision due to accounting error in Samsung Bioepis shareholding treatment
- Samsung BioLogics is pursuing lawsuit to cancel the disposition
- Seoul Administrative Court ruled to cancel the disposition in 2020 (1st instance) and 2024 (2nd instance) → FSC is appealing
- **Risk**: If lawsuit is lost, may affect Samsung Electronics' 2015-2022 **equity method income, investment in affiliates, and retained earnings**
**② Legal Lawsuit Contingent Liabilities**
- "Multiple lawsuits, disputes, and regulatory investigations ongoing in the normal course of business with various companies"
- Management believes it will not have a material impact on financial position
- However, **the amount and timing of resource outflow is uncertain**
**③ Provisions**
- **Sales Warranty Provisions**: Estimated costs for product quality assurance, exchange, and defect repair
- **Emission Liabilities**: Estimated costs for excess greenhouse gas emission allowances
---
### 5) HBM and AI Semiconductor Business Outlook - Company's Official Position
#### 📌 2024 Q4 Performance Situation
> "While inventory adjustments by mobile/PC customers intensified, **demand for HBM and server DRAM remained strong** as major data centers and tech companies continued AI-focused investments."
#### 📌 2025 Outlook and Risks
> "AI demand momentum is expected to continue, but data center and OEM customer demand may fluctuate depending on GPU supply conditions, and **HBM demand volatility continues due to AI semiconductor export controls**."
#### 📌 Company's Response Strategy
- Portfolio shift to high-value products (HBM, DDR5, LPDDR5x, QLC SSD)
- Accelerated transition to leading-edge processes
- Focus on responding to server DDR5 and high-capacity server QLC SSD demand
#### 📌 Foundry Business
> "The 2025 Foundry market is expected to see **double-digit growth** centered on the Advanced node market as HPC/AI application demand remains strong"
- Expanding mobile/HPC demand based on stable 4nm process yield
- GAA-based 3nm process mobile production shipment preparation in H1 2025
---
## 🚨 3 Key Points to Watch When Investing in Samsung Electronics
### 1️⃣ **HBM Competitiveness Gap and Geopolitical Risks**
- Lagging position compared to SK Hynix in HBM technology and customer acquisition
- **Potential sharp decline in China-bound HBM demand** if U.S. strengthens AI semiconductor export controls
- Uncertainty in expanding Samsung Electronics' share as major customers like NVIDIA diversify supply
### 2️⃣ **Owner Family Share Sales and Governance Instability**
- **Continued annual share sales of approximately 2 trillion KRW** by Hong Ra-hee, Lee Boo-jin, and Lee Seo-hyun
- Concerns about management stability due to Chairman Lee Jae-yong's low personal shareholding (1.63%)
- High dependence on affiliates such as Samsung Life (8.51%) and Samsung C&T (5.01%)
- Possibility of additional share sales for future inheritance tax payments
### 3️⃣ **Potential Impact of Samsung BioLogics Accounting Treatment Lawsuit**
- Administrative lawsuit ongoing with **unpredictable outcome**
- If lost, retroactive revision of 2015-2022 financial statements → possible decrease in retained earnings
- Risk of **consolidated financial statement distortion** from changes in affiliate investment and equity method income
- Company states it is difficult to reflect in financial statements at this time
---
**Conclusion**: While Samsung Electronics benefits from AI/HBM demand momentum, it is necessary to closely monitor the technology gap compared to competitors, geopolitical uncertainty, and governance-related risks. Dividends are stable, but given the high volatility in net income, it is advisable to focus on whether absolute dividend amounts are maintained rather than payout ratios.
### Compatibility
#### 📊 6 Core Analysis Categories
| Category | Analysis Purpose | Key Analysis Capabilities |
|---------|-----------------|--------------------------|
| **🔍 Disclosure Information Analysis** | Capture corporate disclosure patterns and management change signals | • Analyze disclosure frequency and types to predict management status changes<br>• Real-time monitoring of key disclosures including major reports and governance changes<br>• Automatic extraction of financial statement notes to uncover hidden risks<br>• Structured parsing of business content and company overview to understand strategic intent |
| **📈 Periodic Report Key Information Analysis** | Extract core management information from annual, quarterly, and semi-annual reports | • Analyze executive compensation and reward systems to assess governance risks<br>• Analyze dividend policy and shareholder return strategy sustainability<br>• Identify capital financing intentions through capital change patterns (capital increase/decrease, treasury stock)<br>• Evaluate organizational stability through employee status and labor cost structure |
| **💰 Periodic Report Financial Information Analysis** | Assess financial soundness based on financial statements and XBRL data | • Comprehensive analysis of profitability (ROA/ROE), stability (debt ratio), growth, and activity indicators<br>• Time-series trend analysis to detect financial performance volatility and outliers<br>• Identify relative position compared to industry averages and assess competitiveness<br>• Analyze overall group financial soundness structure based on consolidated financial statements |
| **👥 Comprehensive Share Ownership Information Analysis** | Evaluate governance stability and management control change risks | • Monitor management control stability through major shareholder and related party shareholding changes<br>• Early detection of hostile takeover possibilities through 5%+ shareholder shareholding changes<br>• Analyze insider trading suspicions through executive and major shareholder stock transactions<br>• Assess M&A defense capabilities and governance risks through minority shareholder distribution |
| **⚡ Major Report Analysis** | Capture strategic change signals and restructuring indicators | • Analyze business restructuring strategies through business acquisition/transfer, merger/division decisions<br>• Understand strategic changes through asset transfer and putback option contracts<br>• Early warning system for management crises including bankruptcy, business suspension, and rehabilitation procedures<br>• Evaluate legal risks and financial impact through lawsuit filing information |
| **💼 Securities Filing Analysis** | In-depth analysis of financing structure and debt risks | • Analyze debt securities (corporate bonds, convertible bonds, bonds with warrants) issuance terms<br>• Assess liquidity and refinancing risks through short-term/long-term debt structure<br>• Verify fund usage transparency through public/private capital usage details<br>• Analyze global financing strategies and foreign exchange risks through overseas listing decisions |
#### 🎯 Advanced Analysis Features
- **Financial Notes Auto-Extraction**: Automatically parse and store consolidated and separate financial statement notes as structured data
- **Business Content Parsing**: Dynamically parse Section II (Business Content) to structure subsections including business overview, operating status, and financial soundness
- **Company Overview Parsing**: Dynamically parse Section I (Company Overview) to extract key information including company history, capital changes, and total shares
- **Structured Data Search**: Semantic-based search across tables and paragraphs to instantly find detailed information related to specific keywords (e.g., lawsuits, contingent liabilities, HBM)
- **Intelligent XML File Selection**: Automatically select optimal business reports from ZIP files, excluding audit reports, to maximize analysis efficiency
#### 🧠 Ontology-Based Knowledge Graph System
- **Automatic Knowledge Graph Generation**: Automatically generates structural knowledge graphs when caching disclosure documents
- Entities: Corporation, Disclosure, Section, Subsection, Table, Paragraph
- Relationships: Automatically extracts structural relationships such as Corporation-Disclosure, Disclosure-Section, Section-Subsection
- Metadata: Includes node count, edge count, generation timestamp, etc.
- **Natural Language Query Engine**: Relationship-based search using knowledge graphs
- Natural language query support: "business content subsections", "financial notes sections", etc.
- Structural relationship exploration: Automatically explores relationships between sections and subsection hierarchy
- Automatic related entity discovery: Returns all nodes and edges related to the query
- **Domain-Specific Synonym Expansion**: Dynamic term expansion for improved search accuracy
- Domain separation: Insurance (synonyms_insurance.json), Finance (synonyms_finance.json), etc.
- Automatic expansion: Automatically includes related synonyms during search (e.g., "CSM" → "Contract Service Margin", "Insurance Contract Assets")
- Match score: Provides confidence score for expanded terms
- **Self-Improving Synonym Learning**: Automatically discovers synonyms by analyzing search results and knowledge graphs
- Automatic learning: Analyzes co-occurrence patterns from search results
- Knowledge graph relationship analysis: Calculates confidence based on shared nodes and path length in the graph
- Confidence-based auto-approval: High confidence (≥0.8) auto-approved, low confidence added to manual review queue
- Manual review system: Queue management and statistics provided
## Quick Start Guide
### 1. Authentication Setup
First, obtain your OpenDART API key:
1. Go to [OpenDART](https://opendart.fss.or.kr/)
2. Sign up and request an API key
3. Wait for approval and receive your API key
### 2. Installation
```bash
# Clone repository
git clone https://github.com/ChangooLee/mcp-opendart.git
cd mcp-opendart
# [IMPORTANT] Ensure you are using Python 3.10 or higher. See: 'Checking and Installing Python 3.10+' below.
# Create virtual environment
python3.10 -m venv .venv
source .venv/bin/activate
# Install package
# python 3.10 >= required
python3 -m pip install --upgrade pip
uv pip install -e .
```
---
## Checking and Installing Python 3.10+
# Check Python version (must be 3.10 or higher)
python3 --version
# If your Python version is lower than 3.10, follow the instructions below to install Python 3.10 or higher:
### macOS
- Download the latest Python installer from the official website: https://www.python.org/downloads/macos/
- Or, if you use Homebrew:
```sh
brew install python@3.10
```
After installation, you may need to use `python3.10` instead of `python3`.
### Windows
- Download and run the latest Python installer from: https://www.python.org/downloads/windows/
- During installation, make sure to check "Add Python to PATH".
- After installation, restart your terminal and use `python` or `python3`.
### Linux (Ubuntu/Debian)
- Update package list and install Python 3.10:
```sh
sudo apt update
sudo apt install python3.10 python3.10-venv python3.10-distutils
```
- You may need to use `python3.10` instead of `python3`.
### Linux (Fedora/CentOS/RHEL)
- Install Python 3.10:
```sh
sudo dnf install python3.10
```
## IDE Integration
MCP OpenDART is designed to be used with AI assistants through IDE integration.
### Claude Desktop Configuration
1. Click hamburger menu (☰) > Settings > Developer > "Edit Config" button
2. Add the following configuration:
```json
{
"mcpServers": {
"mcp-opendart": {
"command": "YOUR_LOCATION/.venv/bin/mcp-opendart",
"env": {
"OPENDART_API_KEY": "API-KEY",
"OPENDART_BASE_URL": "https://opendart.fss.or.kr/api/",
"HOST": "0.0.0.0",
"PORT": "8000",
"TRANSPORT": "stdio",
"LOG_LEVEL": "INFO",
"MCP_SERVER_NAME": "mcp-opendart"
}
}
}
}
```
### Streamable HTTP Configuration (Optional)
You can also run with streamable-http using HTTP transport:
```json
{
"mcpServers": {
"mcp-opendart": {
"command": "YOUR_LOCATION/.venv/bin/mcp-opendart",
"env": {
"OPENDART_API_KEY": "API-KEY",
"OPENDART_BASE_URL": "https://opendart.fss.or.kr/api/",
"HOST": "0.0.0.0",
"PORT": "9000",
"TRANSPORT": "http",
"LOG_LEVEL": "INFO",
"MCP_SERVER_NAME": "mcp-opendart"
}
}
}
}
```
> [!NOTE]
> - When `TRANSPORT="http"` is set, the server runs with streamable-http
> - Endpoint: `http://HOST:PORT/mcp`
> [!NOTE]
> - `YOUR_LOCATION`: Replace with the actual path where your virtual environment is installed
> - `API-KEY`: Replace with your OpenDART API key
### Environment Variables
- `OPENDART_API_KEY`: Your OpenDART API key
- `OPENDART_BASE_URL`: API base URL (defaults to official URL)
- `HOST`: Server host (default: 0.0.0.0)
- `PORT`: Server port (default: 8000)
- `TRANSPORT`: Transport method (stdio recommended, set to http for streamable-http support)
- `LOG_LEVEL`: Logging level (INFO, DEBUG, etc.)
- `MCP_SERVER_NAME`: Server name
## Financial Notes Auto-Extraction and Search System
### System Architecture
```mermaid
graph TD
A[Download Disclosure Document] --> B[XML Parsing]
B --> C{Financial Notes Exist?}
C -->|Yes| D[Extract Financial Notes]
C -->|No| E[Guide to Search Other Reports]
E --> F[LLM Selects Other Report]
F --> A
D --> G[Section Classification]
G --> H[Consolidated Notes]
G --> I[Separate Notes]
H --> J[Extract Tables]
H --> K[Extract Paragraphs]
I --> L[Extract Tables]
I --> M[Extract Paragraphs]
J --> N[Structured JSON Storage]
K --> N
L --> N
M --> N
N --> O[Save to disclosure_cache]
O --> P[Searchable State]
P --> Q[Keyword Search]
Q --> R[Table Search Results]
Q --> S[Paragraph Search Results]
```
### Caching Structure
```
disclosure_cache/
├── financial_notes_{rcp_no}/
│ ├── metadata.json
│ ├── disclosure_{rcp_no}.json
│ ├── consolidated_notes/
│ │ ├── metadata.json
│ │ ├── tables/
│ │ │ ├── table_001.json
│ │ │ ├── table_002.json
│ │ │ └── ...
│ │ └── paragraphs/
│ │ ├── para_001.json
│ │ ├── para_002.json
│ │ └── ...
│ └── separate_notes/
│ ├── metadata.json
│ ├── tables/
│ └── paragraphs/
```
### Search Features
- **Table Search**: Keyword search in headers and data cells
- **Paragraph Search**: Keyword search in financial statement note paragraphs
- **Section-based Search**: Search only consolidated or separate notes
- **Case Sensitivity**: Optional case-sensitive search
- **Synonym Auto-Expansion**: Automatic search term expansion based on domain-specific synonym dictionaries (e.g., "CSM" → "Contract Service Margin", "Insurance Contract Assets")
- **Knowledge Graph Query**: Natural language structural relationship exploration (e.g., "business content subsections", "financial notes sections")
## Tools
### OpenDART Tools
- `ds001_disclosure`: Search and retrieve disclosure information
- `ds002_periodic`: Access periodic report key information
- `ds003_financial`: Access periodic report financial information
- `ds004_ownership`: Access comprehensive share ownership information
- `ds005_major`: Access major report key information
- `ds006_securities`: Access securities filing key information
<details>
<summary>Main Tools List</summary>
| Category | Tools |
|----------|-------|
| **Disclosure Information** | `get_corporation_code_by_name`, `get_disclosure_list`, `get_corporation_info`, `get_disclosure_document`, `get_corporation_code` |
| **Periodic Report Key Information** | `get_annual_report`, `get_quarterly_report`, `get_semi_annual_report` |
| **Periodic Report Financial Information** | `get_single_acnt`, `get_multi_acnt`, `get_xbrl_file`, `get_single_acc`, `get_xbrl_taxonomy`, `get_single_index`, `get_multi_index` |
| **Comprehensive Share Ownership Information** | `get_major_shareholders`, `get_executive_holdings` |
| **Major Report Key Information** | `get_major_reports`, `get_business_reports` |
| **Securities Filing Key Information** | `get_securities_filing`, `get_prospectus` |
| **Financial Notes Search** | `search_financial_notes` |
| **Knowledge Graph Query** | `query_knowledge_graph` |
</details>
## Troubleshooting & Debugging
### Common Issues
- **Authentication Failures**:
- Check if your API key is valid and active
- Verify your API key has the necessary permissions
- Check if you've exceeded the API rate limit (20,000 calls/day)
- **Data Access Issues**:
- Some data may require additional permissions
- Certain data might have delayed access (up to 24 hours)
- Check if the company is within your accessible range
- **Connection Problems**:
- Verify your internet connection
- Check if the OpenDART API service is available
- Ensure your firewall isn't blocking the connection
### Debugging Tools
```bash
# Enable verbose logging
export LOG_LEVEL=DEBUG
# View logs
tail -f opendart.log
# Test API connection
python -m mcp_opendart test-connection
```
## Security
- Never share your API key
- Keep `.env` files secure and private
- Use appropriate rate limiting
- Monitor your API usage
- Store sensitive data in environment variables
## Contributing
We welcome contributions! If you'd like to contribute:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request
## License
This project is licensed for non-commercial, personal, research, or educational use only. Commercial use, redistribution, and commercial derivative works are strictly prohibited. See the [LICENSE](LICENSE) file for details.
This is not an official OpenDART product. OpenDART is a registered trademark of the Financial Supervisory Service of Korea.
