Content
<div align="center">
# Tool List
**Claude reads DART OpenAPI directly**
[](https://www.python.org/downloads/)
</div>
---
## Deployment Status
The public installation guide for DartLens has ended as of 2024-06-01.
New installations are now guided through a purchase notice, which includes installation commands and guidelines. Existing users who have already installed can continue using their current version, but new distributions, installation support, and utilization templates will be organized based on the purchaser's package.
## Why is it needed?
When showing AI a disclosure PDF, it **guesses numbers and provides incorrect answers** - sales, operating profit, share ratio, and reporting date are all hallucinations.
**dartlens** connects Claude directly to the Financial Supervisory Service's [DART OpenAPI](https://opendart.fss.or.kr), allowing AI to read and analyze **disclosure documents and standardized financial statements**, not guesses.
```
❌ "Samsung Electronics' operating profit was around 35 trillion last year" (guess, incorrect)
✅ "Samsung Electronics' 2024 business report shows an operating profit of 32.7 trillion, up 395% from 6.6 trillion in the previous year" (DART original)
```
> "Summarize Samsung Electronics' recent quarterly report" · "List Kakao's disclosures from the past month" · "LG Energy Solution's operating profit trend" · "Samsung Electronics' shareholders with a 5% stake or more" · "Hyundai Motor executives' stock purchases"
This project is **independent** of the sister project [stocklens-mcp](https://github.com/Johnhyeon/stocklens-mcp) (Naver stock-based market data). Claude combines the two MCPs to perform stock analysis.
## Key Features
- 📑 **7 tools** — company search, disclosure lists and documents, financial statements (summary and full), 5% rule, insider trading
- 🔐 **API keys stored in OS keychain** (Windows DPAPI / macOS Keychain / Linux Secret Service) — no plain text config storage
- 💸 **DART OpenAPI** — 1,000 requests per minute, 20,000 requests per day
- 🧠 **Token optimization** — unit compression + report indexing + keyword matching (`find=...`) for lightweight processing
- 🩺 **`dartlens-doctor`** — automatic diagnosis with cause and solution commands
## Installation Guide
The guide provided to purchasers includes:
1. `uv` verification and installation
2. DartLens MCP installation
3. DART API key input and verification
4. Claude Desktop or Claude Code MCP automatic registration
5. Installation diagnosis and first execution confirmation
No direct installation commands are posted in the public README.
## Operation Verification
In Claude:
```
Show me Samsung Electronics' recent disclosures
```
If the company name, disclosure list, and reporting date appear, the installation is complete.
## Installation Issue Diagnosis
```bash
dartlens-doctor
```
Automatic 5-step verification of `uv`, packages, commands, config, and API keys. Displays cause and solution commands.
---
## Key Storage Policy
`dartlens-setup` does not store **DART API keys in plain text in `claude_desktop_config.json`**.
- Default: store keys in OS keychain
- Windows → Credential Manager (DPAPI · user account-level automatic encryption)
- macOS → Keychain
- Linux → Secret Service (GNOME Keyring / KDE Wallet)
- Config files contain only `mcpServers.dartlens.command`, not keys
- Server checks `DART_API_KEY` environment variable at boot; if not found, retrieves from keychain
If `DART_API_KEY` is stored in plain text in the JSON config, running `dartlens-setup` again will automatically migrate it to the keychain and remove it from JSON.
### Plain Text Mode (headless environment fallback)
For environments without OS keychain support (servers, some WSL/Docker), use `--plaintext` for explicit opt-out:
```bash
dartlens-setup --plaintext <KEY>
```
Existing plain text storage in `env.DART_API_KEY` in JSON config.
---
## Tools
| Tool | Purpose |
|---|---|
| `search_company` | Company name/code → corp_code + company overview |
| `list_disclosures` | Disclosure lists by period and type (rcept_no return) |
| `get_disclosure_detail` | Short disclosures extract text; long reports provide index + viewer URL. `find="keyword"` for text search |
| `get_major_accounts` | Key financials from regular reports (sales/operating profit/net profit/assets/liabilities/equity — current/previous/previous previous year comparison) |
| `get_full_financial` | Full financial statements. sj_div(BS/IS/CIS/CF/SCE) required |
| `get_order_backlog` | Structured order backlog and contract amount trends from reports |
| `get_major_holders` | 5% rule large holdings changes — foreign/fund/activist investor tracking |
| `get_insider_trades` | Insider trading — executives and major shareholders' stock ownership |
| `scan_earnings_season` | Earnings season scan — top N Markdown for chat |
| `export_earnings_scan` | Export scan results to `.xlsx`/`.csv` files. Korean Excel recommends `.xlsx` |
### Recommended Workflow
```
# Disclosure flow
search_company("Samsung Electronics") → corp_code "00126380"
list_disclosures(corp_code="00126380", days=30) → rcept_no list
get_disclosure_detail(rcept_no="...") → short disclosures, long reports provide index
get_disclosure_detail(rcept_no="...", find="new business") → keyword match ±300 characters
# Financial flow
search_company("Samsung Electronics") → corp_code
get_major_accounts(corp_code, bsns_year=2024, reprt_code="annual") → key figures
get_full_financial(corp_code, bsns_year=2024, reprt_code="annual",
fs_div="CFS", sj_div="IS") → entire profit/loss
get_order_backlog(corp_code, years=3) → order backlog/contract amount trend
# Earnings season scan
scan_earnings_season(period="2026Q1", universe="kospi", top_n=30) → chat-ready summary table
export_earnings_scan(period="2026Q1", universe="all",
output_format="xlsx", max_rows=1000) → Excel file + row/column verification
export_earnings_scan(period="2026Q1", universe="all",
output_format="both", amount_unit="eok") → XLSX + CSV simultaneous generation
# Terminal Excel file generation
uvx --from dartlens-mcp dartlens-export-earnings --period 2026Q1 --universe all --sort-by op_yoy --max-rows 3000 --format xlsx
# PowerShell: use quotes for comma-separated corp_code list
uvx --from dartlens-mcp dartlens-export-earnings --period 2026Q1 --universe "00126380,00631518" --format both
# Shareholding flow (capital movement not visible in market data)
search_company("Samsung Electronics") → corp_code
get_major_holders(corp_code, limit=10) → 5% rule reports (foreign/fund/activist)
get_insider_trades(corp_code, limit=10) → executives and major shareholders' stock purchases
```
---
## Supported Environments
| Environment | Support |
|------|------|
| Claude Desktop (app, Win/macOS) | ✅ |
| Claude Code (CLI, Win/macOS/Linux/RasPi) | ✅ |
| Claude.ai (web) | ❌ local MCP not supported |
`dartlens-setup --target {claude-desktop, claude-code, both}` allows explicit selection. Default `auto` detects environment.
## Principles
- **Only DART OpenAPI** is used. No scraping from Naver, Daum, etc.
- Market data, charts, and supply/demand are handled by stocklens; **disclosure and financial statement data** are handled by dartlens.
- The two servers do not call each other; **Claude is the coordinator**.
- No investment recommendations or trading signals are provided; only data.
## Operation Principles
DartLens does not provide investment recommendations, buy/sell signals, or automated trading functions. It is a data tool that connects DART disclosures and standardized financial data for Claude to read.
## License
MIT
