[한국어](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
[Demo video will be added here]
### Compatibility
| Feature | Support Status | Description |
|---------|---------------|-------------|
| **Disclosure Information** | ✅ Fully supported | Company information and disclosure document search |
| **Periodic Report Key Information** | ✅ Fully supported | Key information from annual, quarterly, and semi-annual reports |
| **Periodic Report Financial Information** | ✅ Fully supported | Financial statements and XBRL data |
| **Comprehensive Share Ownership Information** | ✅ Fully supported | Major shareholders and executive holdings information |
| **Major Report Key Information** | ✅ Fully supported | Key information from major business reports |
| **Securities Filing Key Information** | ✅ Fully supported | Key information from securities issuance filings |
| **Financial Notes Auto-Extraction** | ✅ Fully supported | Automatic extraction and caching of consolidated and separate financial statement notes |
| **Structured Data Search** | ✅ Fully supported | Semantic-based search across tables and paragraphs |
## 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
## 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` |
</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.
