Content
# Tool List
**Ask Korean filings like an analyst. KReports turns DART into investor-ready signals for Claude.**
[English](#english) |
[](https://pypi.org/project/kreports/)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/Apache-2.0)
[](https://modelcontextprotocol.io)
<p align="center">
<img src="docs/images/kreports-demo.gif" alt="KReports MCP demo showing a plain-language Korean filing question flowing into source-grounded investor and auditor answers" width="840">
</p>
<p align="center">
<sub>Ask once in Claude. KReports turns Korean DART filings into source-grounded paragraphs, tables, diagrams, and next checks for investor and auditor workflows.</sub>
</p>
---
<a id="english"></a>
## English
> Built by a Big4 auditor for investors who want to read Korean filings without living inside DART.
### Why KReports
Korean listed companies already tell you a lot in DART filings: revenue, cash flow, auditor changes, restatements, subsidiary structures, audit fees, business risks, and shareholder events.
The problem is not lack of data. The problem is that the data is buried across filings, tables, footnotes, and company codes.
KReports turns that raw disclosure pile into questions you can ask Claude:
- "Is this company financially healthy, or just optically cheap?"
- "Did anything suspicious show up in accounting, cash flow, auditor history, or restatements?"
- "How does this company compare with peers in the same Korean industry?"
- "What recent disclosure events should I read before buying or holding?"
### What it does
KReports connects [DART](https://dart.fss.or.kr) (Korea's SEC) to Claude via the [Model Context Protocol](https://modelcontextprotocol.io). It covers 3,900+ KOSPI/KOSDAQ/KONEX listed companies and converts filings into structured financial intelligence.
### Two workflows
KReports serves two audiences from the same DART source: investors who need fast judgment signals, and audit/accounting professionals who need evidence and risk coverage.
#### Investors
You do not need to know accounting standards to start. Ask in plain language and use KReports as a pre-buy or portfolio checkup.
| Investor question | What KReports checks |
|-------|-------|
| "Is Samsung Electronics still a high-quality business?" | ROE, operating margin, revenue growth, debt ratio, free cash flow, cash conversion |
| "What should I worry about before buying Kakao?" | Restatements, amendments, Beneish M-Score, auditor changes, non-clean opinions, cash-flow gaps |
| "Is this stock strong compared with peers?" | KSIC industry P25/P50/P75 and peer list |
| "Did recent filings contain shareholder-friendly or dilution events?" | Treasury stock, capital raise, CB/BW/EB, merger/split, large contract, litigation, amendments |
| "Can I trust the numbers?" | DART original data, accounting policy footnotes, audit opinions, audit fees, subsidiary auditor matrix |
The new `get_investor_signals` tool gives one compact first-pass read: quality profile, accounting/governance risk, recent investor-relevant disclosure events, and plain takeaways.
#### Audit and accounting professionals
KReports also preserves the audit lens it was born from. It helps turn scattered DART filings into risk leads that can be traced back to source filings.
| Professional question | What KReports checks |
|-------|-------|
| "Is there a going-concern issue I should not miss?" | Capital impairment, two-year operating losses, high debt, weak interest coverage, negative operating cash flow, non-clean opinion |
| "Did prior-year numbers move after the next annual report?" | Prior-period restatement candidates across annual filings |
| "Did the auditor change, and how long has the current auditor served?" | Auditor, opinion, change flag, consecutive years |
| "Is independence worth reviewing?" | Audit fee, non-audit fee, NAS ratio |
| "What does the group audit perimeter look like?" | Subsidiary and affiliate auditor matrix |
| "Which accounting policies matter for this company?" | Standard K-IFRS policy footnote extraction |
### Setup
Two modes — pick one.
---
#### Option A: Hosted service (no API key needed)
Connect to the pre-built database. No DART key. No data collection. Just add the MCP endpoint.
**Claude Code:**
```bash
claude mcp add kreports -- uvx --from kreports kreports-mcp
```
**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"kreports": {
"command": "uvx",
"args": ["--from", "kreports", "kreports-mcp"]
}
}
}
```
> Hosted endpoint coming soon. Follow the repo for the release.
---
#### Option B: Self-hosted (bring your own data)
Build and own your local database. Requires a free DART API key.
```bash
pip install kreports
echo "DART_API_KEY=your_key" > .env
kreports init
kreports sync-companies
kreports collect-seed --size small # ~350 companies, ~20 min
kreports serve
```
Get a free DART API key at [opendart.fss.or.kr](https://opendart.fss.or.kr).
### Then ask Claude
```
"Samsung Electronics investor signal summary — quality, accounting risk, recent disclosure events"
"What recent disclosure events should I read before buying Kakao?"
"Compare Samsung Electronics operating margin to semiconductor peers"
"SK Hynix going concern risk — 6-factor scorecard"
"Show auditor history for Kakao for the past 5 years"
"Has Celltrion restated any prior period figures?"
"Subsidiary auditor matrix for POSCO group"
"Beneish M-Score for this company — earnings manipulation risk"
```
### MCP Tools (12)
| Tool | Best for | What it returns |
|------|----------|-----------------|
| `search_company` | Everyone | Corp code, market, stock code |
| `get_investor_signals` | Investors | Quality checks, accounting risk score, recent investor-relevant disclosure events |
| `get_financial_snapshot` | Investors / analysts | Revenue, OP, NI, FCF, ROIC, CCC by year |
| `compare_to_industry` | Investors / analysts | KSIC P25/P50/P75 vs. peers (single metric) |
| `compare_to_industry_multi` | Investors / analysts | Multi-metric × multi-year P25/P50/P75 matrix + subject percentile. Adaptive ladder (p3→p2) + sector mutual exclusion + opt-in size bucket |
| `get_business_overview` | Investors / auditors | Business report narrative (overview, risk, MD&A) |
| `score_going_concern` | Audit / credit risk | 6-factor 100-pt deduction scorecard + grade |
| `detect_restatement` | Audit / accounting risk | Prior period adjustments across annual filings |
| `get_accounting_policy` | Accounting / audit planning | 15 standard K-IFRS policy items from footnotes |
| `get_audit_history` | Audit / governance | Auditor, opinion, change flag, consecutive years |
| `get_subsidiary_auditors` | Group audit / governance | Group audit matrix across subsidiaries |
| `get_industry_audit_landscape` | Audit / governance | Industry audit market: auditor share (count + asset-weighted), Big4 share, non-qualified opinion rate (N-yr), avg tenure, subject's auditor |
All tools accept company name, 6-digit stock code, or 8-digit DART corp_code interchangeably.
### For Python developers
```bash
pip install kreports
```
```python
import kreports
# Financial snapshot
snap = kreports.get_financial_snapshot("005930", years=3)
# Going concern score
gc = kreports.score_going_concern("005930")
print(f"Score: {gc['score']}/100 ({gc['grade']})")
# Industry benchmark
bench = kreports.compare_to_industry("005930", metric="영업이익률")
# Investor signal summary
signals = kreports.get_investor_signals("005930")
```
### Full local setup (self-hosted)
```bash
pip install kreports
# Set API key
echo "DART_API_KEY=your_key" > .env
# Initialize and collect
kreports init
kreports sync-companies
kreports enrich-market
kreports collect-seed --size small # ~350 companies, ~20 min
# or
kreports collect-all --year-from 2021 --year-to 2025 # all 3,900+ companies
# Start MCP server
kreports serve
```
### Remote HTTP MCP (claude.ai web)
```bash
kreports serve-http --port 8765 --token your_bearer_token
# then expose via ngrok, Fly.io, or any HTTPS host
```
Add `https://your-host/mcp` as a custom connector in claude.ai Settings → Integrations.
### Going Concern Scorecard
100-point deduction system (K-IFRS audit standard):
| Factor | Deduction | Threshold |
|--------|----------:|-----------|
| Capital impairment | −30 | Total equity < 0 |
| 2-year consecutive operating loss | −20 | OP < 0 for 2 years |
| Debt ratio > 200% | −15 | Debt / Equity > 200% |
| Interest coverage < 1.0 | −15 | OP / Interest expense < 1 |
| Negative operating cash flow | −10 | Operating CF < 0 |
| Non-clean audit opinion | −10 | Qualified / Adverse / Disclaimer |
Grades: **Stable** (80+) / **Caution** (60–79) / **Warning** (40–59) / **Danger** (<40)
### Data coverage
| Entity | Coverage |
|--------|---------|
| Listed companies | 3,900+ (KOSPI + KOSDAQ + KONEX) |
| Financial history | Up to 5 years |
| Auditor records | Opinion, firm, consecutive years |
| Audit fees | Audit + non-audit, NAS ratio |
| Industry benchmarks | KSIC 2/3-digit, 8 metrics |
| Accounting policies | 15 standard K-IFRS items |
| Investor signals | Quality checks, accounting/governance risk, disclosure event categories |
### Architecture
```
kreports/
├── mcp/ MCP stdio + HTTP servers (10 tools)
├── analysis/ Public Python API (11 functions, JSON-safe)
├── collector/ DART API collectors (9 modules)
├── processor/ XBRL/XML parsers
├── judge/ Risk flag engine (Beneish, Going Concern)
├── db/ SQLAlchemy models (8 tables, SQLite)
└── cli/ Typer CLI (17 commands)
dashboard/ Optional Streamlit UI (9 pages)
```
### CLI reference
```
kreports init Initialize DB
kreports sync-companies Sync DART company registry
kreports enrich-market Fill market + KSIC codes
kreports collect-seed Collect core companies (small/medium/full)
kreports collect <ticker> Collect single company
kreports collect-all Batch collect all listed companies
kreports collect-auditors Collect auditor history
kreports collect-audit-fees Collect audit / non-audit fees
kreports collect-policies Persist accounting policy footnotes
kreports compute-flags Recompute Beneish + going concern flags
kreports serve Start MCP stdio server
kreports serve-http Start MCP HTTP server
kreports mcp-doctor Smoke-check MCP environment
kreports mcp-config Print IDE config JSON
```
### Requirements
- Python 3.11+
- [Free DART OpenAPI key](https://opendart.fss.or.kr)
### License
Apache 2.0
### Author
**capitalparser** — Big4 CPA, 7 years in external audit. Built to replace the annual DART manual labor that every audit team dreads.
<a id=""></a>
