한국 공시를 AI에서 찾기 어려울 때: korean-dart-mcp 설치·검증 - dea:no

한국 공시를 AI에서 찾기 어렵다면 korean-dart-mcp를 검토할 수 있지만, 먼저 Node.js 버전·OpenDART 인증키·저장소 상태를 확인해야 합니다.

기준일: 2026-09-03. 이 글은 낯선 저장소 코드를 실행하지 않고 공개 저장소의 루트 파일, README, package.json, LICENSE와 금융감독원 OpenDART 안내를 정적으로 대조했습니다. 따라서 실제 MCP 호출을 성공시켰다는 사용 후기가 아니라, 설치 전에 확인할 수 있는 범위와 격리 검증 절차를 설명합니다. 공식 루트는 korean-dart-mcp GitHub 저장소입니다.

Table of Contents

한국 공시를 AI 작업에 연결할 때 생기는 문제

OpenDART는 공시보고서 원문과 주요 공시·재무·지분 정보를 API로 활용하게 해 주지만, 개발자가 직접 붙이려면 회사 식별, 공시 유형, 기간, 원문 파일, 재무 데이터의 호출 흐름을 따로 다뤄야 합니다. 금융감독원의 OpenDART 오픈API 소개는 개인·기업·기관이 공시 원문과 구조화된 주요 정보를 활용할 수 있다고 설명합니다. 이 사실은 데이터의 공식 출처를 보여 주지만, 특정 MCP 도구의 정확성이나 투자 판단의 타당성까지 보증하지는 않습니다.

korean-dart-mcp는 이 문제를 MCP 서버와 CLI라는 접점으로 좁힙니다. 저장소 README는 OpenDART API들을 여러 도구로 묶고 공시 검색·재무·지분·XBRL·첨부 문서 변환을 AI 클라이언트에서 호출하는 구성을 제시합니다. 핵심 가치는 새로운 공시 데이터베이스라기보다 공식 데이터에 접근하는 반복 작업을 대화형 도구의 입력으로 정리하는 데 있습니다.

이 차이를 이해하면 도입 범위도 선명해집니다. 공시 원문을 찾고 비교할 시간을 줄이고 싶은 개발자에게는 조사 보조 도구가 될 수 있습니다. 반대로 실시간 주가, 주문, 포트폴리오 자동매매, 투자 수익을 제공하는 제품으로 읽으면 범위를 벗어납니다. README도 차트와 실시간 주가가 없고 투자 판단은 사용자의 몫이라고 적고 있습니다.

설치 전에 확인할 저장소와 런타임

이번 정적 검토에서 GitHub API는 저장소를 public으로, archived를 false로, 라이선스를 MIT로 반환했습니다. 기본 브랜치는 main이며 루트에는 README.md, README-EN.md, package.json, package-lock.json, LICENSE, src, scripts, .env.example 등이 보입니다. 공개 저장소라는 사실은 접근성을 뜻할 뿐 유지보수나 보안을 보장하지 않으므로, 설치 시점의 커밋을 별도로 기록해야 합니다.

package.json의 현재 버전은 0.10.1이고 engines.node는 >=20.19.0입니다. 의존성에는 MCP SDK, SQLite 바인딩, XML·PDF 처리기, dotenv 등이 포함되어 있습니다. 이 목록은 설치 전에 네이티브 모듈과 문서 처리 의존성이 생길 수 있음을 알려 줍니다. Windows에서 npx가 인식되는지, 현재 셸의 Node.js가 요구 버전 이상인지 먼저 확인하세요. 설치 전에는 공식 package.json을 다시 읽어 버전과 엔진 조건을 고정하는 편이 안전합니다.

최근 활동성은 2026-07-30 커밋 0701f41229c0f2a7680f89356086b8bb2c7a0dd9를 기준으로 확인했습니다. 커밋 메시지는 DART 접근 시 브라우저 사용자 에이전트 사칭을 제거하고 robots 제한 경로를 경고하는 내용입니다. GitHub 릴리스 API에서 공개 릴리스는 0건이었습니다. 그러므로 최신 릴리스 설치라고 표현하기보다 검증한 main 커밋과 확인일을 남겨야 합니다. 최근 커밋이 있다는 것 역시 기능 품질의 자동 증명이 아닙니다.

설치 경로와 인증키 설정 순서

README가 제시하는 가장 짧은 설치 경로는 Node.js 20.19 이상에서 npx -y korean-dart-mcp setup을 실행하는 것입니다. setup은 OpenDART 인증키 입력, 사용 중인 AI 클라이언트 선택, 설정 파일 패치와 클라이언트 재시작을 안내하는 대화형 흐름입니다. Windows에서는 npx 호출을 cmd /c로 감싸는 설명도 있으므로 운영체제와 셸에 따라 결과가 달라질 수 있습니다.

node --version
npx -y korean-dart-mcp setup

위 명령은 문서에 적힌 설치 예시를 보여 주는 것이며, 이번 검증에서 실행한 명령은 아닙니다. 실제로 실행할 때는 먼저 격리된 테스트 사용자와 빈 작업공간을 준비하고 설치 전후 설정 파일의 diff를 남기세요. AI 클라이언트의 전역 설정을 자동 패치하게 두면 의도하지 않은 프로젝트까지 도구가 보일 수 있으므로, 처음에는 프로젝트 단위 설정이나 수동 설정을 선택하는 편이 영향 범위를 줄입니다.

OpenDART 인증키는 금융감독원 사이트의 인증키 신청 절차에서 발급받습니다. 공식 OpenDART 개발가이드는 공시검색, 기업개황, 공시서류 원본파일, 고유번호 같은 API 영역을 안내합니다. 키를 README나 설정 파일 저장소에 커밋하지 말고 운영체제의 비밀 저장소나 로컬 환경 변수로 주입하세요. 로그·스크린샷·AI 대화 기록에 키가 남지 않았는지 설치 후 바로 확인해야 합니다.

첫 연결의 성공 기준은 설치 명령이 끝났다는 사실이 아닙니다. Node.js 버전, 설정 파일에 기록된 실행 경로, 인증키가 참조되는 위치, 클라이언트가 도구 목록을 읽는지, 실패 시 오류가 키 값을 노출하지 않는지를 각각 기록해야 합니다. 한 단계라도 불명확하면 다음 단계로 넘어가지 말고 설정 파일을 백업한 뒤 원인을 분리하세요.

활용 흐름: 공시 검색에서 원문 검토까지

안전한 활용은 질문을 작은 조회로 나누는 것에서 시작합니다. 최근 공시를 모두 분석해 달라고 한 번에 요청하기보다 회사명 확인, 기간과 공시 유형 설정, 결과 목록 확인, 필요한 원문 하나 선택, 마지막으로 비교·요약의 순서를 따릅니다. 이 순서는 AI가 잘못 해석한 회사명이나 기간을 초기에 발견하게 해 줍니다.

첫 단계는 회사 식별입니다. 동명이인이나 약칭을 그대로 넘기지 말고 종목코드와 회사명을 확인하세요. 둘째 단계는 공시 검색입니다. OpenDART 공식 안내가 설명하듯 공시 원문과 주요 정보를 활용할 수 있으므로 결과에서 보고서 종류와 접수일을 함께 기록해야 합니다. 셋째 단계는 원문 확인입니다. 요약 결과만 저장하지 말고 중요한 숫자·일자·문장을 원문 보고서와 대조합니다.

저장소 README의 도구 구성을 활용한다면 공시 검색, 재무 계정, XBRL, 지분 정보, 첨부 문서 추출을 서로 다른 작업으로 취급하세요. 재무비율은 기간과 분모를 확인하고, XBRL은 계정명과 택소노미를 확인하며, PDF나 HWP 변환 결과는 표와 각주가 손실되지 않았는지 원문 일부와 대조합니다. 긴 응답을 사실 목록으로 복사하기보다 어떤 공식 응답의 어느 필드를 읽었는지를 남기는 것이 재검증에 유리합니다.

업무에 적용할 때는 결과를 투자 권유가 아닌 조사 메모로 저장하는 편이 적절합니다. 정정공시가 있으니 위험하다고 단정하지 말고 조회 기간·검색 조건·원문 링크·AI가 제시한 신호·사람이 다시 확인할 항목을 한 표에 분리하세요. 데이터가 없거나 API가 제한되면 빈 결과와 실패 이유를 기록해야 하며, 빈 결과를 이상 없음으로 바꾸면 안 됩니다.

직접 확인한 범위와 재현 가능한 점검표

이번 실행에서 수행한 직접 검증은 공개 HTTP 응답과 정적 파일 비교입니다. GitHub API로 저장소 메타데이터를 읽고 main 브랜치의 README.md·package.json·LICENSE·.gitignore를 raw URL에서 각각 요청했습니다. 네 파일은 모두 200 OK였고, 루트 목록에 src와 scripts가 포함된 것을 확인했습니다. 이 방식은 코드 실행 없이 문서·권리·설치 단서를 확인하는 점검입니다.

항목	확인 결과	도입 시 해석
저장소 상태	public, archived=false, 기본 브랜치 main	접근 가능하지만 유지보수 보장은 아님
권리 문서	LICENSE 200 OK, GitHub 메타데이터 MIT	라이선스 의무를 따로 검토
런타임	Node.js >=20.19.0	설치 전 로컬 버전 확인
설치 단서	README에 npx setup과 클라이언트 설정 흐름	설정 파일 diff와 영향 범위 확인
활동성	최근 커밋 2026-07-30, 공개 릴리스 0건	커밋과 확인일을 고정
실행 경계	이번 검증에서는 저장소 코드 미실행	실제 설치는 격리 환경에서 별도 수행

정적 패턴 검색에서는 README·package.json·LICENSE·.gitignore 안에서 os.system, subprocess, shell=True, eval(, child_process, exec( 문자열을 찾지 못했습니다. 이 결과는 저장소 전체에 취약점이나 악성 동작이 없다는 인증이 아닙니다. src와 scripts의 실제 동작, 설치 과정에서 내려받는 패키지, AI 클라이언트가 읽는 설정은 실행 전에 별도로 검토해야 합니다.

재현 점검은 네 단계로 나누세요. 첫째, 테스트 계정과 빈 디렉터리에서 Node.js와 npx 버전을 기록합니다. 둘째, setup 전후 설정 파일을 비교해 추가된 실행 파일·인자·환경 변수의 위치를 확인합니다. 셋째, 테스트용 OpenDART 키로 회사명 조회 1건과 공시 목록 조회 1건만 수행하고 요청 범위와 응답 필드를 저장합니다. 넷째, 키를 지운 뒤 로그·임시 파일·셸 히스토리에 값이 남지 않았는지 확인합니다. 실제 운영 키로 이 절차를 재현하지 마세요.

한계와 대안: 이 도구가 맞지 않는 경우

첫 번째 한계는 데이터 최신성과 API 제약입니다. OpenDART는 공식 데이터를 제공하지만 조회 가능한 범위, 요청량, 인증키 정책은 서비스 운영 조건에 따릅니다. 저장소 README의 기능 소개나 예시 수치가 현재 계정·기간·응답과 항상 같다고 가정하면 안 됩니다. 사용 시점의 OpenDART 공지와 개발가이드를 확인하고 응답의 기준일을 결과와 함께 보관하세요.

두 번째 한계는 AI 해석입니다. MCP는 도구 호출을 쉽게 만들지만 회사명·기간·단위·연결재무와 별도재무를 AI가 잘못 선택할 수 있습니다. 재무 수치를 근거로 결론을 내릴 때는 원문과 산식을 사람이 재검토하고 투자 판단이나 자동 주문으로 연결하지 마세요. 필요한 것이 pandas 기반 대량 분석이라면 OpenDartReader나 dart-fss처럼 Python 데이터프레임 중심 대안을 비교하는 편이 맞을 수 있습니다.

세 번째 한계는 운영 복잡성입니다. MCP 클라이언트마다 설정 파일 위치와 재시작 방식이 다르고 Node.js 네이티브 의존성이 설치를 막을 수 있습니다. 팀이 중앙 서버와 감사 로그를 이미 운영한다면 독립 CLI를 각자 설치하기보다 승인된 중계 계층에서 OpenDART 호출과 키 권한을 관리하는 설계가 적합할 수 있습니다. 개인이 공시 원문을 대화형으로 탐색한다면 프로젝트 범위의 작은 테스트부터 시작하세요.

네 번째 한계는 문서 변환의 손실 가능성입니다. HWP·PDF·XBRL을 Markdown으로 바꾸면 표의 병합 셀, 각주, 단위, 페이지 경계가 달라질 수 있습니다. 변환된 텍스트만으로 숫자를 확정하지 말고 원문 파일의 해당 페이지나 XML 요소를 함께 확인하세요. 결과가 길어질수록 모델의 요약 누락도 늘 수 있으므로 필요한 섹션만 추출하는 방식이 안전합니다.

라이선스와 보안 주의사항

package.json은 MIT를 선언하고 저장소에는 LICENSE 파일이 있습니다. MIT는 복사·수정·배포를 폭넓게 허용하지만 저작권 고지와 라이선스 문구를 보존해야 하며 소프트웨어는 보증 없이 제공됩니다. 의존성 패키지와 OpenDART 데이터 이용약관은 별도 조건일 수 있으므로 저장소 라이선스만 보고 전체 사용 조건이 같다고 결론 내리지 마세요. 권리 원문은 공식 LICENSE에서 확인합니다.

인증키: OpenDART 키를 코드, Git, Notion, 프롬프트, 스크린샷, 브라우저 콘솔, 오류 보고서에 넣지 않습니다. 키가 노출되면 사용량을 확인하고 즉시 폐기·재발급 절차를 검토하세요.
최소 권한: AI 클라이언트가 읽고 쓸 수 있는 디렉터리를 테스트 작업공간으로 제한합니다. WordPress 자격증명, SSH 키, 브라우저 세션, 홈 디렉터리를 같은 클라이언트에 노출하지 마세요.
설정 diff: setup이 수정한 파일과 추가한 인자를 확인하고 원격 URL·자동 업데이트·실행 경로가 예상과 다른지 검토합니다.
네트워크: OpenDART와 패키지 레지스트리로 전송되는 데이터, 요청량, 캐시 파일의 위치를 확인합니다. 공시 결과에 개인 메모나 비공개 고객 정보가 섞이지 않게 하세요.
출력 검수: AI가 만든 요약에서 회사명·기간·단위·음수·천 단위 구분을 원문과 맞추고 확정적 수익·위험 표현은 근거가 없으면 제거합니다.

도입 결론과 다음 행동

korean-dart-mcp는 한국 공시 원문과 구조화 정보 탐색을 AI 클라이언트의 작업 흐름에 연결하는 오픈소스 선택지입니다. 다만 설치 성공은 데이터 검증 성공과 다르고 저장소의 MIT 표기는 API·의존성·생성 문서의 모든 권리를 대신하지 않습니다. Node.js 20.19 이상인지 확인하고 커밋을 고정한 격리 환경에서 설정 diff와 최소 조회를 검증한 뒤 업무 범위를 단계적으로 넓히세요.

공시 데이터의 공식 제공 범위는 OpenDART 오픈API 소개에서, 공시검색과 기업개황 등 API 영역은 OpenDART 개발가이드에서 다시 확인할 수 있습니다. AI 에이전트 스킬과 설정 파일을 비교하는 관점은 dea:no Agent Skills 실전 가이드와 오픈소스 도구의 문서·설치·보안 점검 순서는 기존 오픈소스 실전 글에서 비교할 수 있습니다.

자주 묻는 질문

Q. 실제로 코드를 실행해 봤나요?
A. 아닙니다. 2026-09-03 기준으로 공개 HTTP 응답, 파일 존재, 문서 내용, 저장소 메타데이터만 정적으로 확인했습니다. 실제 MCP 호출은 별도 격리 환경에서 해야 합니다.

Q. OpenDART 인증키가 꼭 필요한가요?
A. 저장소 README는 setup 흐름에서 OpenDART 인증키를 입력하도록 안내합니다. 키 발급과 이용 조건은 금융감독원 공식 사이트에서 확인하고 로컬 비밀 저장소로 관리하세요.

Q. 이 도구로 주가나 매매도 할 수 있나요?
A. 이 저장소의 README는 차트·실시간 주가가 없고 투자 판단은 사용자의 몫이라고 설명합니다. 공시 조사와 매매 시스템을 같은 것으로 취급하지 마세요.

Q. 설치 후 바로 운영해도 되나요?
A. Node.js 버전, 설정 diff, 키 노출 여부, 최소 조회 2건, 원문 대조, 로그 정리를 통과한 뒤에만 제한적으로 도입하세요. 검증되지 않은 설치를 운영 계정과 연결하지 않는 것이 안전합니다.

출처와 검증일

공식 저장소 루트 — 공개·보관 상태, 루트 파일, 기능 소개 확인
공식 README — npx 설치, 클라이언트 설정, 활용 범위와 한계 확인
공식 package.json — 버전, MIT 선언, Node.js 요구사항 확인
공식 커밋 기록 — 최근 활동과 릴리스 부재 확인
금융감독원 OpenDART 오픈API 소개 — 공시 원문과 주요 정보 제공 범위 확인
금융감독원 OpenDART 개발가이드 — 공시검색·기업개황·원문파일 API 영역 확인
MIT License — 권리와 보증 부인 조항 확인

검증일: 2026-09-03 KST. 저장소, 패키지, OpenDART 정책과 API 조건은 이후 바뀔 수 있으므로 설치·호출 시점에 공식 페이지를 다시 확인해야 합니다.