DART 리스크 분석 MCP

공시 기반 불공정거래 위험 모니터링 + 공시·재무 탐색 — 금융감독원 전자공시(DART)에서 위험 신호를 읽어내고, 공시 원문·재무제표·감사보고서를 파고드는 MCP 서버입니다.

📖 처음이신가요? 사전 지식 없이 읽을 수 있는 프로젝트 소개 페이지를 먼저 보세요.

🔎 설치 없이, 키 없이 바로 — 리스크 뷰어에서 종목명만 넣으면 하루 5곳까지 키 없이 스캔됩니다. 아래 리스크 뷰어 절 참고.

공시는 누구에게나 공개돼 있지만, 한 건씩 따로 공개됩니다. 불공정거래의 신호는 낱장이 아니라 흐름과 연결에 있습니다 — 12개월 안에 자본을 세 번 주무르는 리듬, 회사마다 이름을 바꾸는 투자조합 뒤의 같은 임원, 조달 명분과 다른 곳으로 흘러간 돈. 이 도구는 Claude 같은 AI가 DART에 직접 접속해 그 흐름을 읽게 해 줍니다.

그리고 신호를 찾지 않을 때도 씁니다. 도구 34개 중 위험 분석 전용은 일부이고, 나머지는 조회·확인용입니다 — 공시 원문을 섹션·페이지로 읽고, 주석 본문을 낱말로 검색하며, 재무제표 전체 계정을 감사보고서 원문의 계정명과 대조해 냅니다(DART API가 주는 이름은 XBRL 표준 태그라 회사가 쓴 말과 다를 때가 있습니다 — 「이익잉여금」이 원문에는 「결손금」인 식). 비상장 외부감사대상 법인의 재무제표·주석도 감사보고서 원문에서 읽고, 최대 20개사 × 10개 연도를 나란히 비교합니다. 「이 회사 매출원가가 얼마야?」 같은 평범한 질문에도 답합니다.

🚗 그런데 "MCP"가 뭐예요?

한마디로 AI에게 바깥 세상과 연결되는 "옵션 장치"를 달아 주는 표준 규격입니다(Model Context Protocol). 자동차에 빗대면 쉽습니다.

• 그냥 AI 채팅 = 깡통차. 잘 달리지만 아는 건 배운 것뿐이라, 오늘 올라온 공시나 내 데이터는 보지 못합니다.
• '프로젝트' 같은 기본 기능을 쓰는 정도 = 에어컨 옵션 하나 단 셈. 조금 편해지죠.
• MCP를 붙이면 = 내비게이션을 단 것과 같습니다. AI가 바깥(여기선 DART 전자공시)에 직접 접속해 길을 찾아 줍니다. 잘 엮어 쓰면 여러 도구를 알아서 조합하는 자율주행급까지 갑니다.

다른 걸로 빗대도 똑같습니다.

• 📷 사진앱 필터 — 같은 사진도 필터를 입히면 전혀 달라지듯, 같은 AI도 MCP라는 도구를 끼우면 할 수 있는 일이 달라집니다.
• 🍜 라면 + 계란 — 라면(기본 AI)도 맛있지만 계란을 넣으면 다른 음식이 되죠. 이 프로젝트가 바로 그 '계란' — AI에게 DART 공시를 직접 읽는 능력을 얹어 줍니다.

설치하면 Claude Desktop·Claude Code·Cursor 등에서 한국어 질문만으로 공시 분석이 됩니다. 도구 이름을 외울 필요도 없어요.

예: "이 다섯 회사에 공통으로 등장하는 인물 있어?" → 5개사의 CB 인수자·등기임원을 다년으로 겹쳐 공통 행위자를 찾아 줍니다.

🔎 설치 없이 먼저 써 보기 — 리스크 뷰어

dart-risk-mcp.vercel.app — 아무것도 설치하지 않고, 키도 없이 종목명만 넣으면 됩니다.

MCP 설치는 터미널이나 Claude Desktop이 필요합니다. 뷰어는 브라우저만 있으면 되니, 이 도구가 무엇을 보는지 먼저 눈으로 확인하고 설치를 결정하세요.

종목명을 넣으면 나오는 첫 화면. 왼쪽은 이 기간 가장 무거운 신호와 「먼저 볼 공시」, 오른쪽은 신호가 어느 유형에 몰렸는지와 시간순 연결(신호 체인)입니다.

어떻게 시작하나

1. 링크를 엽니다 → 종목명(예: 셀트리온)이나 6자리 종목코드를 입력
2. 최근 1년 공시를 그 자리에서 실시간 수집해 분석합니다(수십 초)
3. 끝. 회원가입도, 설치도, 키 입력도 없습니다

하루 5곳까지 키 없이 조회됩니다. 더 보시려면 본인의 무료 DART API 키를 넣으면 됩니다 — 발급은 증빙서류 없이 즉시 되고 하루 20,000건입니다. 입력한 키는 브라우저에만 저장되고 서버에 남지 않습니다.

화면 다섯 개

대시보드가 보여주는 것

관측 타임라인 · 신호 해설 · 최대주주 변경 상세 · 손익구조 급변 · 재무 핵심 · 회전율 추세 · 메자닌(CB·BW·EB) 현황 · 주식 수 변동(희석) · 배당과 순이익 · 조달 자금의 행방 · 임원·주요주주 소유보고 시계열 · 감사의견 3개년 · 채무증권 미상환 잔액 · 공시와 시장(1년 종가·거래량 위에 관찰 신호 마커와 코스피·코스닥 지수를 겹친 차트 + 사건별 전후 대조표 — 본인의 KRX Open API 키가 있을 때만, 약관상 운영자 키로는 조회하지 않습니다).

수치는 표로 나오고 증감에는 ▲▼가 붙습니다. 색은 그 지표에서 통상 개선으로 읽히는 쪽을 가리키며, 좋고 나쁨이 갈리는 지표는 색 없이 둡니다.

같은 화면을 내려가면 나오는 재무 패널. 같은 ▼라도 부채비율은 초록(내려가는 쪽이 통상 개선), 유동비율은 빨강이고, 방향에 좋고 나쁨이 없는 매입채무회전율은 색이 없습니다. 값이 없는 칸은 비워 두지 않고 ―로 적습니다.

뷰어도 점수를 매기지 않습니다

MCP 도구와 같은 원칙입니다 — 등급·점수·매수 추천이 없고, 공시라는 공개 기록의 사실 표기와 원문 링크만 냅니다. 모든 행에서 DART 원문으로 바로 갈 수 있습니다.

⚠ 뷰어는 웹 축약판입니다. 위험 신호 42종·복합 패턴 11종을 1년 창에서 보여주지만, 다년 조회·비상장 감사보고서·주석 낱말 검색·원문 계정명 대조 같은 것은 MCP 도구(아래 34개)에 있습니다. 뷰어에서 흥미로운 회사를 찾고, 깊게 파는 것은 MCP로 — 그 순서를 권합니다.

설치하기

설치 방법은 두 가지입니다. Claude Desktop을 쓴다면 방법 A(원클릭) 가 가장 쉽습니다 — 터미널이 전혀 필요 없어요.

방법 A — 원클릭 확장(.mcpb) · Claude Desktop · 터미널 0 ⭐

1. 최신 릴리스에서 dart-risk-mcp.mcpb 파일을 내려받습니다.
2. Claude Desktop → 설정(Settings) → Extensions 를 열고, 받은 .mcpb 파일을 창에 끌어다 놓습니다(또는 "확장 설치"로 열기).
3. 설치 화면의 DART API 키 칸에 키를 붙여넣으면 끝입니다. (키가 없으면 아래 방법 B의 3단계에서 무료로 2분이면 발급 — 발급만 하고 이 칸에 붙여넣으면 됩니다.)

파이썬을 직접 설치할 필요 없이 Claude Desktop이 알아서 처리합니다.

Claude Desktop → 설정 → 확장 프로그램. 이 화면에 .mcpb 파일을 끌어다 놓으면 설치됩니다.

방법 B — 터미널로 설치 (Cursor·Windsurf·Claude Code 등 그 외 클라이언트)

처음이라도 순서대로만 따라오면 약 10분이면 끝납니다.

⛔ 가장 먼저 알아둘 것

아래에 나오는 pip install ... 같은 명령어는 Claude(또는 ChatGPT) 채팅창에 입력하는 게 아닙니다. 컴퓨터의 "터미널"(명령 프롬프트) 이라는 검은 창에 입력하는 것입니다. 채팅창에 붙여넣으면 아무 일도 일어나지 않아요. 터미널 여는 법은 바로 아래 1단계에 있습니다.

1단계 — 터미널(명령어 입력하는 창) 열기

명령어를 입력하는 전용 프로그램입니다. 운영체제에 따라 여는 법이 다릅니다.

• Windows — 키보드에서 ⊞ Windows 키를 누르고 powershell 또는 cmd 라고 입력한 뒤 Enter. 파란색(또는 검은색) 창이 뜹니다.
• Mac — ⌘ Command + Space 를 눌러 Spotlight를 열고 터미널 또는 terminal 이라고 입력한 뒤 Enter. 흰색/검은색 창이 뜹니다.

이 창이 앞으로 명령어를 입력할 곳입니다. 채팅창이 아니라 이 창입니다.

이렇게 검은 창이 뜨면 준비 완료. (Windows 예시 — cmd든 powershell이든 괜찮습니다.)

2단계 — 파이썬(Python)이 설치돼 있는지 확인

이 도구는 파이썬이라는 프로그램 위에서 돌아갑니다. 대부분의 컴퓨터엔 없거나 버전이 낮으니 먼저 확인합니다.

터미널에 아래를 그대로 입력하고 Enter:

python --version

• Python 3.11.x 처럼 3.11 이상 숫자가 나오면 → 통과. 3단계로 가세요.
• Python 2.x 가 나오거나, 'python'은(는) 내부 또는 외부 명령... 이 아닙니다 / command not found 같은 오류가 나오면 → 아직 없는 것입니다. 아래에서 설치하세요.

3단계 — DART API 키 발급 (무료·2분)

DART(금융감독원 전자공시)에서 데이터를 가져오려면 본인 전용 열쇠(키)가 필요합니다. 무료입니다.

1. opendart.fss.or.kr 접속 → 오픈API 신청 → 인증키 신청/관리.
2. 이메일 주소를 넣고 인증하면 길고 복잡한 문자열(예: a1b2c3d4e5...) 하나를 즉시 받습니다. 이게 API 키입니다.
3. 이 키를 메모장 같은 곳에 잠깐 복사해 두세요. 잠시 뒤 붙여넣습니다. (일 20,000건까지 조회 가능)

4단계 — 도구 설치하기

이제 1단계에서 연 터미널 창으로 돌아와, 아래 두 줄을 한 줄씩 입력하고 각각 Enter를 누릅니다.

pip install dart-risk-mcp

python -m dart_risk_mcp.setup

• 첫 줄(pip install ...)은 도구를 내려받아 설치합니다. 글자가 주르륵 지나가다 멈추면 완료된 것입니다.
• 둘째 줄(python -m dart_risk_mcp.setup)은 컴퓨터에 깔린 AI 프로그램(Claude Desktop 등)을 자동으로 찾아 연결해 줍니다. 중간에 "API 키를 입력하세요" 라고 물으면, 3단계에서 복사해 둔 키를 붙여넣고 Enter를 누르세요.
  • 터미널에 키를 붙여넣는 법: Windows는 창 안에서 마우스 오른쪽 클릭, Mac은 ⌘ Command + V.
  • 기존에 쓰던 다른 MCP 설정이 있어도 지우지 않고 그대로 둡니다.

5단계 — AI 프로그램 재시작하고 질문하기

1. Claude Desktop(또는 사용 중인 AI 프로그램)을 완전히 종료했다가 다시 켭니다. (연결을 새로 읽어들이기 위해 꼭 필요합니다.)

2. 이제 채팅창에 평소처럼 한국어로 질문하면 됩니다:

   "삼성전자 최근 1년 공시 흐름 요약해줘"

도구 이름을 외울 필요가 전혀 없습니다. 질문만 하면 AI가 알아서 알맞은 도구를 골라 씁니다. 잘 안 된다면 아래 "자주 막히는 부분"을 보세요.

*질문하면 이렇게 도구 사용 권한을 묻는 창이 뜹니다. **"항상 허용"*을 누르면 다음부터 묻지 않습니다 — 이 화면이 보이면 설치 성공입니다.

{
  "mcpServers": {
    "dart-risk": {
      "command": "python",
      "args": ["-m", "dart_risk_mcp"],
      "env": { "DART_API_KEY": "발급받은_키" }
    }
  }
}

💡 설치가 부담스럽다면 — 아무것도 깔지 않고 키도 없이 하루 5곳까지 써 보는 리스크 뷰어가 있습니다.

무엇을 하나

실제 대화는 이렇게 흘러갑니다

결과물은 표가 아니라 대화 속 서술형 리포트로 나오고, 후속 질문으로 꼬리를 물며 깊어집니다. 아래 AI 응답은 이 문서를 쓰면서 **실제로 MCP를 호출해 받은 응답(2026-07-18)**에서 그대로 발췌한 것입니다(인물명만 마스킹).

👤 "제이스코홀딩스, 요즘 공시에 이상한 흐름 있어?"

🤖 track_capital_structure — "🎯 12개월 안에 자본 관련 공시가 지나치게 자주 반복되고 있습니다 — 증자·감자·자사주·CB/BW/EB/RCPS 같은 자본 구조 변경이 12개월 안에 3건 이상 몰리는 상태입니다. 정상적인 기업은 자본 구조를 자주 건드리지 않습니다. (…) 자본 이벤트 총 47건 · 12개월 최대 집중도: 26건"

👤 "이름 바꿔가면서 여러 회사를 드나드는 세력은 어떻게 잡아? 이 다섯 회사에 공통 인물 있는지 봐줘"

🤖 find_actor_overlap (5개사 · 3년) — "이번 비교에서 2곳 이상에 동시에 등장한 인수자가 3명/건 발견됐습니다. ⚠️ 신○수 — 3개 회사에 [임원] 경로로 등장 · ⚠️ 신○규 — 2개 회사 · ⚠️ 이○영 — 2개 회사 (…)"

👤 "저 사람 워치리스트에 올려두고, 다음에 회사 늘려서 다시 봐줘"

🤖 manage_watchlist — "✅ '신○수' 갱신 — 총 3개사: CG인바이츠, 제이케이시냅스, 헬스커넥트" — 다음부터 find_actor_overlap(watchlist="…") 한 줄로 회사군 전체 재조회.

더 긴 대화 데모는 소개 페이지에 있습니다.

도구 34개 — 질문으로 찾기

도구 이름을 외울 필요 없습니다. AI에게 질문하면 알맞은 도구가 호출됩니다.

🔀 공시 도구를 여러 개 쓰고 있다면 — 이 서버의 이름은 dart-risk 입니다. 「dart-risk로 셀트리온 봐줘」처럼 앞에 붙이면 이쪽으로 옵니다. dartrisk · 다트리스크 · 다트 리스크 라고 불러도 같은 곳을 가리킵니다(서버가 스스로 알립니다). 다른 DART 도구를 밀어내지는 않습니다 — 재무제표·원문 조회는 익숙한 도구를 쓰시면 됩니다.

실측으로 검증합니다

아래는 실제 DART API 응답에서 나온 결과입니다(해당 시점 기준, 사실 표기).

• 임원 겸직으로 세력 추적 — 무관해 보이는 5개 상장사를 3년 조회 → 같은 인물이 3개사 등기임원으로 겹치고 동행 인물 2명이 함께 드러남 (find_actor_overlap)
• 자본 주무르기 리듬 — 한 코스닥사에서 12개월 내 자본 이벤트 집중 + 공시의무 위반 동반 → capital_churn_anomaly 패턴 라이브 발화
• 연결<별도 역전 — 연결 순이익 4,189억 < 별도 1조 48억(−58.3%) 자동 표시 → 종속회사 합산 손실 확인 지점 (CFS_OFS_REVERSAL)
• XBRL 좁은 추출 — 요약 재무 API에 없는 감가상각비를 사업보고서 XBRL에서 추출(연결 43.6조/39.6조) → Beneish DEPI·TATA 복원

검증 방식: 유가증권·코스닥 10개사 × 32개 도구의 실측 골드 출력 314건 + 테스트 5,700여 개가 저장소에 있으며, 모든 변경은 이 실측 출력과 대조해 회귀 검증됩니다. 라이브로 재현된 적 없는 신호는 CLAUDE.md의 검증 매트릭스에 ⚠로 정직하게 표기합니다.

출력 원칙 — 점수를 매기지 않습니다

이 도구의 가장 중요한 설계 결정은 **"무엇을 하지 않는가"**입니다.

• 점수·등급 없음 — "위험도 82점", "고위험" 같은 표기를 일절 하지 않습니다. 정량화된 낙인은 그 자체로 판정이 되고 투자 권유로 오독됩니다. 이 원칙은 자동 회귀 테스트(tests/test_golden_output_hygiene.py)가 기계적으로 지킵니다.
  • 한정 예외: 공개 리스크 뷰어는 신호에 2단계 관찰 우선순위(주의/참고)를 배지로 표시합니다. 이는 "무엇부터 볼 것인가"의 정렬 표시이지 위험 판정·점수·등급이 아니며, 뷰어 화면에 같은 취지의 면책이 함께 표기됩니다. MCP 도구 출력에는 적용되지 않습니다.
• 사실 표기, 판정 없음 — "연결 순이익이 별도보다 58% 작습니다"까지만 말하고 "분식 의심"이라고 말하지 않습니다. 모든 출력에 근거 공시 접수번호가 붙습니다.
• 인물 낙인 없음 — 행위자 조회는 공개기록 등장 사실만 반환하며, 항상 동명이인 가능성과 원본 확인 필요를 고지합니다.
• 하나의 한국어 서술 출력 — level/mode/format 분기가 없습니다. 원시 데이터가 필요하면 원문 도구(get_disclosure_document 등)를 조합하세요.

이 도구가 하지 않는 것

행위자 레지스트리(opt-in)와 연결망

• 공개기록 행위자 레지스트리 — lookup_known_actor 등이 참조하는 인물 데이터는 v1.5.0부터 이 저장소·배포물에 포함되지 않습니다(빈 스켈레톤만 동봉). 원본은 제작자가 비공개로 관리하며, 조회 참여를 원하면 제작자에게 연락해 읽기 전용 접근을 요청하세요(opt-in). 명단 관련 이의·문의도 같은 경로로 받습니다.
• 행위자 연결망 시각화 — 반복 등장 행위자와 회사의 연결망을 보여주는 인터랙티브 화면을 별도로 운영 중입니다(열기). 화면에는 실명이 포함되며, 표기는 공시에 적힌 명단을 그대로 옮긴 사실 표기이지 판정이 아니고 동명이인·동명 법인은 미확인입니다.
• 위 두 가지 모두 문의는 제작자 GitHub 프로필의 연락처로 보내 주세요.

개발자 안내

git clone https://github.com/anboyu-alt/dart-risk-mcp.git && cd dart-risk-mcp
pip install -e . && pip install pytest
python -m pytest -q                      # 전체 테스트 (API 키 불필요)
python scripts/regen_goldens.py --dry-run  # 실측 골드 재생성 매트릭스 확인 (키 필요)

• 아키텍처·34개 도구 상세·DART 엔드포인트 맵·신호 추가 방법: CLAUDE.md (개발자 가이드)
• 변경 이력: Releases
• 외부 의존성은 mcp, requests 둘뿐입니다(최소 의존성 원칙). HTML 파싱도 표준 라이브러리로 처리합니다.
• PR 환영합니다. 단, 비범위 항목(점수 부여·실시간 알림·매매 추천 등)은 설계 결정과 충돌하므로 받지 않습니다.

라이선스 · 크레딧

• MIT License — 자유롭게 사용·수정·배포할 수 있습니다.
• 일부 재무 분석 로직(업종별 회계정책 맵, 주석 분류, Beneish 변수, 감사인 별칭 등)은 capitalparser/kreports-dart-mcp(Apache 2.0)에서 이식했습니다 — 상세 내역은 THIRD_PARTY_NOTICES.md.
• 데이터 출처: 금융감독원 DART OpenAPI.

⚠️ 면책: 본 도구의 모든 출력은 공시라는 공개 기록의 사실 표기이며, 특정 기업·인물에 대한 판정이나 투자 권유가 아닙니다. 중요한 판단 전에는 반드시 DART 원문 공시를 직접 확인하세요.