Comparable Company Server

회사명(또는 종목코드)과 기간·재무제표 종류를 물어보면 DART OpenAPI를 직접 호출해 재무제표를 마크다운 표로 바로 반환하는 MCP(Model Context Protocol) 서버

Claude Desktop / Claude Code에서 자연어로 "삼성전자 2023년 1분기 재무상태표 보여줘"처럼 물어보면, DART 전자공시 원본 수치를 표로 정리해 원문 링크와 함께 돌려줍니다.

---

주요 기능

툴	설명
find_company	회사명 또는 종목코드 6자리 → DART corp_code 식별
get_financial_statement	재무제표를 조회해 마크다운 표로 반환 (DART 원문 링크 동봉)

• 연결(CFS) 우선, 없으면 개별(OFS) 자동 폴백 — 어느 쪽을 썼는지 fs_div_used로 명시
• 표준계정(account_id) 기반 파싱 — 계정과목명이 회사·연도별로 달라도 방어
• TTL 캐시(24시간) — 같은 요청 반복 시 DART 재호출 없이 캐시 사용
• 일일 한도 초과(status 020) 처리 — 캐시가 있으면 캐시로 응답, 없으면 명확히 안내(크래시 없음)
• 출처 동봉 — 표 하단에 rcept_no 기반 DART 원문 링크를 붙여 사용자가 직접 검증 가능
• 대차평형 정합성 검증 — 자산총계 = 부채총계 + 자본총계 여부를 자동 확인, 불일치 시 warnings에 경고

---

설치

사전 요건

• Python 3.11+
• DART OpenAPI 키 (opendart.fss.or.kr 가입 후 발급)

패키지 설치

git clone https://github.com/sonjong980304/comparable-company-mcp.git
cd comparable-company-mcp

python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt

환경변수 설정

cp .env.example .env
# .env 열어서 DART_API_KEY 입력

.env 예시:

DART_API_KEY=발급받은_DART_키

---

Claude Desktop / Claude Code 등록

~/Library/Application Support/Claude/claude_desktop_config.json(macOS) 또는 ~/.claude/settings.json(Claude Code)에 추가:

{
  "mcpServers": {
    "dart-financials": {
      "command": "/절대경로/.venv/bin/python3",
      "args": ["/절대경로/server.py"],
      "env": {
        "DART_API_KEY": "발급받은_DART_키"
      }
    }
  }
}

venv python 절대경로는 source .venv/bin/activate && which python3, 프로젝트 경로는 pwd로 확인하세요. 설정 후 Claude Desktop을 완전 종료(Cmd+Q) 후 재시작하면 적용됩니다.

---

사용 예시

Claude에게 자연어로 입력합니다:

삼성전자 2023년 1분기 재무상태표 보여줘

get_financial_statement 툴로 005930의 2022년 손익계산서를 알려줘

파라미터

get_financial_statement(company, year, period, statement_type, fs_div_preference)

파라미터	값	기본값
company	회사명 / 종목코드 6자리 / corp_code 8자리	(필수)
year	사업연도 (예: 2023)	(필수)
period	1분기 · 반기(=2분기·상반기) · 3분기 · 사업보고서(=연간·4분기·전체)	사업보고서
statement_type	재무상태표 · 손익계산서 · 포괄손익계산서 · 현금흐름표 · 자본변동표 · 전체	전체
fs_div_preference	CFS(연결) · OFS(개별)	CFS

예시 응답 (table 필드)

## 삼성전자 2022년 사업보고서 재무상태표

| 계정과목 | 금액 |
|---|---:|
| 자산총계 | 455조 9060억원 |
| 부채총계 | 93조 6749억원 |
| 자본총계 | 362조 2311억원 |

> 출처: [DART 원문 보기(rcept_no=20230315000123)](https://dart.fss.or.kr/dsaf001/main.do?rcpNo=20230315000123)

get_financial_statement는 위 table 외에도 corp_code, corp_name, fs_div_used, currency, rcept_no, source_url, cached, status, warnings, error_message를 함께 반환합니다.

---

아키텍처

comparable-company-mcp/
├── server.py            # MCP 서버 엔트리포인트 (FastMCP, 2개 툴 배선)
├── dart_financials.py   # fnlttSinglAcntAll 호출 + TTL 캐시 + 020 처리 + 파싱
├── cache_manager.py     # corpCode.xml 다운로드 + parquet 캐시, corp_code 조회
├── params.py            # 한국어 키워드 → DART 파라미터(sj_div, reprt_code) 매핑
├── table_renderer.py    # 파싱 결과 → 마크다운 표 렌더링
├── unit_format.py       # 원 단위 금액 → "조/억원" 사람이 읽는 문자열
├── validate.py          # 대차평형(자산=부채+자본) 등 기초 정합성 검증
├── models.py            # Pydantic 스키마 (CompanyLookupResult, FinancialStatementResult)
├── cache/               # corp_codes.parquet + financials/*.json (재무제표 응답 캐시)
├── tests/               # pytest 단위테스트 (네트워크는 mock)
├── .env.example
├── requirements.txt
└── README.md

캐싱 전략

데이터	파일	갱신 주기
DART corpCode.xml	cache/corp_codes.parquet	최초 1회 (없을 때만 다운로드)
재무제표 응답(JSON)	cache/financials/{corp}_{year}_{reprt}_{fs}.json	TTL 24시간 (초과 시 재호출)

---

환경변수

변수	필수	설명
DART_API_KEY	O	DART OpenAPI 인증키 (발급)

DART 키는 요청 URL에 실리므로 httpx 요청 로그를 WARNING으로 억제해 키 노출을 막습니다. 키는 절대 코드/로그/커밋에 하드코딩하지 말고 .env로만 로드하세요.

---

테스트

pytest            # 순수 로직(포맷·파라미터·표·캐시/020/파싱) 단위테스트, 네트워크는 mock

• 라이브 DART API 호출 테스트는 두지 않습니다(일일 한도 소모 방지). 네트워크 계층(_fetch_fnltt)은 테스트에서 mock 처리합니다.

---

주의사항

• 최초 실행 시 DART corpCode.xml 다운로드가 1회 발생합니다. 이후에는 parquet 캐시를 재사용합니다.
• 연결/개별: 기본은 연결(CFS)이며, 연결이 없으면 개별(OFS)로 자동 폴백하고 fs_div_used에 명시합니다.
• DART 전체 재무제표(fnlttSinglAcntAll)는 2015 사업연도부터 제공됩니다.
• 일일 한도 초과(020) 시 유효한 캐시가 있으면 캐시로 응답하고, 없으면 status="quota_exceeded"로 안내합니다.
• 대차평형 자동 검증: 재무상태표에 자산총계·부채총계·자본총계가 모두 있으면 자산총계 = 부채총계 + 자본총계를 확인하고, 불일치 시 warnings에 표시합니다(계정이 일부 없으면 단정하지 않고 검증을 건너뜁니다).