# k-dart-mcp

**by All Time High**

**여의도불주먹과 함께, AI에 한국 기업 공시를 연결하세요.**

공시 검색부터 재무제표·기업 비교까지. 금융감독원 OpenDART 데이터를 AI가 직접 조회하는 읽기 전용 MCP 서버입니다.

## AI에게 설치 맡기기

Codex·Claude Code·Cursor처럼 **PC에서 설치 명령과 파일 수정을 할 수 있는 AI**에 아래 문장을 보내세요.

```text
https://github.com/prismyoo1231/k-dart-mcp

이 저장소의 INSTALL.md를 읽고 내 AI 앱에 k-dart-mcp를 설치해줘.
기존 MCP 설정은 보존하고, 인증키는 내가 터미널에서 직접 입력하게 해줘.
설치 후 실제 DART 조회가 되는지 확인해줘.
```

**여러분이 준비할 것은 [OpenDART 인증키](https://opendart.fss.or.kr)입니다.** 인증키 신청/관리에서 발급받으세요. 키는 AI 채팅에 보내지 말고 설치 중 안내되는 터미널에 직접 입력합니다.

AI가 Git·Node.js 22 이상과 패키지 관리자를 확인하고, 설치 및 앱 등록을 진행합니다. 실행 환경 설치, 권한 승인, 앱 재시작은 필요할 수 있습니다. 일반 ChatGPT 웹 채팅에 링크만 붙이는 것으로 PC에 설치되지는 않습니다.

## 이런 질문을 할 수 있어요

> 삼성전자 최근 공시 10개를 찾아서 원문 링크와 함께 보여줘.

> SK하이닉스의 2025년 연결 기준 연간 매출과 영업이익을 조회해줘.

> 삼성전자와 SK하이닉스의 2025년 연간 재무정보를 같은 기준으로 비교해줘.

> 카카오의 2025년 연결 현금흐름표를 보여줘.

결과에는 조회 기준과 원문 링크가 포함됩니다. 공시 목록 조회가 본문 분석을 의미하지는 않습니다.

## 제공하는 도구

| 도구 | 기능 |
| --- | --- |
| `search_company` | 회사명·종목코드·DART 고유번호로 기업 검색 |
| `search_disclosures` | 기간별 공시 검색, 정정 표시와 원문 링크, 페이지 정보 |
| `get_financial_summary` | 매출·영업이익·순이익·자산·부채·자본 |
| `get_full_financial_statements` | 재무상태표·손익계산서·포괄손익계산서·현금흐름표·자본변동표 |
| `compare_financials` | 최대 5개 기업을 같은 보고서·연결/별도 기준으로 조회 |

연간·반기·1분기·3분기 보고서, 연결(CFS)·별도(OFS)를 명시적으로 선택합니다. 누락된 금액은 0으로 채우지 않으며, 연결 자료가 없어도 별도로 자동 대체하지 않습니다. 금융업 등 비표준 계정은 요약에서 누락될 수 있으므로 전체 재무제표로 확인하세요.

## 직접 설치하기

Node.js 22 이상과 Git이 필요합니다. npm 예시이며 pnpm도 사용할 수 있습니다.

```sh
git clone https://github.com/prismyoo1231/k-dart-mcp.git
cd k-dart-mcp
npm install --ignore-scripts
node bin/cli.js install --client codex
node bin/cli.js auth
node bin/cli.js doctor
```

`auth`는 **본인이 직접 여는 터미널**에서 실행하세요. 입력한 인증키는 화면에 표시되지 않습니다. `doctor`는 실제 API에 연결해 기업 검색과 공시 조회를 확인합니다.

`--client`에는 `codex`, `cursor`, `claude-desktop`을 사용할 수 있습니다. 등록 후 해당 앱을 재시작하세요. 등록된 서버 이름은 `k-dart`입니다. 서버 파일을 현재 폴더의 절대 경로로 등록하므로 **설치 후 폴더를 이동하거나 삭제하지 마세요.**

자동 등록은 기존 설정을 백업하고 다른 서버·설정을 보존합니다. TOML의 주석과 서식은 재작성될 수 있습니다. 동명의 다른 서버가 있으면 덮어쓰지 않습니다. Claude Desktop 자동 등록은 Windows·macOS를 지원합니다. Claude Code는 아래 수동 설정이나 해당 클라이언트의 MCP 등록 명령을 이용하세요.

### 수동 등록

MCP 설정을 직접 관리한다면 다음 형식을 참고하세요. 경로는 본인 PC의 실제 절대 경로로 바꿉니다.

```json
{
  "mcpServers": {
    "k-dart": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/k-dart-mcp/bin/cli.js"]
    }
  }
}
```

Codex의 `config.toml` 형식:

```toml
[mcp_servers.k-dart]
command = '/absolute/path/to/node'
args = ['/absolute/path/to/k-dart-mcp/bin/cli.js']
```

Windows에서도 실제 경로를 사용하세요. TOML의 작은따옴표는 역슬래시를 그대로 보존합니다. 기존 설정 파일 전체를 예시로 교체하지 말고 서버 항목만 추가하세요.

## 인증키와 데이터

- 우선순위: `DART_API_KEY` 환경변수 → `~/.k-dart-mcp/credentials.json`.
- 키 파일은 **로컬 평문 파일**입니다. POSIX에서는 소유자만 읽고 쓸 수 있게 생성합니다. Windows에서는 사용자 폴더 권한에 의존합니다. 저장 파일과 백업·화면 캡처를 공개하지 마세요.
- 키는 OpenDART 요청에 사용합니다. 별도의 운영 서버나 분석 서비스로 전송하지 않으며, 키가 담긴 URL을 로그에 기록하지 않습니다.
- 조회된 공시·재무 데이터는 AI 앱에 전달됩니다. AI 서비스의 데이터 처리 정책이 적용됩니다.
- 기업 목록은 첫 조회 때 내려받아 메모리에 최대 24시간 보관합니다. 재무·공시 결과를 디스크에 저장하지 않습니다.
- 인증키 교체는 `auth`를 다시 실행한 뒤 MCP 연결을 재시작하세요. 환경변수도 설정되어 있다면 환경변수가 우선합니다.

## 문제가 생기면

| 증상 | 확인할 것 |
| --- | --- |
| 도구가 보이지 않음 | 앱 재시작, MCP 활성화, Node와 서버 파일의 절대 경로 |
| 인증키 없음 | 터미널에서 `node bin/cli.js auth` 실행 후 재시작 |
| 처음 기업 검색이 느림 | 기업 목록을 내려받는 중일 수 있음. 네트워크 확인 |
| `010` / `011` | OpenDART 인증키 발급·사용 상태 |
| `012` | 인증키의 접근 IP 조건 |
| `013` | 해당 기업·기간·보고서에 데이터 없음 |
| `020` | 요청 한도 초과. 반복 호출을 멈추고 OpenDART 이용현황 확인 |
| 요약 금액이 `null` | 표준 계정 미제공 또는 모호한 계정. 전체 재무제표 조회 |

`node bin/cli.js doctor`로 연결을 점검하세요. 오류를 공유할 때 인증키와 키가 들어간 설정은 제외하세요.

## 업데이트 / 연결 해제

설치 폴더에서 `git pull --ff-only` 후 `npm install --ignore-scripts`를 실행하고 앱을 재시작합니다. 직접 수정한 파일이 있다면 먼저 보관하세요. 패키지 업데이트 결과를 테스트한 뒤 사용하세요.

연결을 해제하려면 AI 앱의 MCP 설정에서 `k-dart`를 비활성화하거나 해당 항목만 삭제합니다. 다른 서버 설정은 보존하세요. 저장된 인증키가 더 이상 필요 없다면 `~/.k-dart-mcp/credentials.json`도 직접 삭제합니다.

## 개발 / 검증

```sh
npm install --ignore-scripts
npm run check
npm test
```

테스트는 모의 DART 응답, 설치 설정 보존, 실제 STDIO MCP 연결을 검사합니다. 실제 인증키를 사용하는 네트워크 조회는 자동 테스트에 포함되지 않습니다. `doctor`는 사용자 환경에서 별도로 실행합니다. macOS 앱에서의 실제 등록·실행은 해당 OS에서 확인해야 합니다.

금융감독원 공식 제품이 아닌 독립 오픈소스입니다. [OpenDART](https://opendart.fss.or.kr)의 공개 API를 사용하며 이용 조건·한도는 발급 계정에 따릅니다. 원문과 정정 공시를 확인하고, 보고서 기준·사업연도·통화를 맞춰 사용하세요.

## 참고

- [OpenDART 공시 검색](https://opendart.fss.or.kr/guide/detail.do?apiGrpCd=DS001&apiId=2019001)
- [OpenDART 기업 고유번호](https://opendart.fss.or.kr/guide/detail.do?apiGrpCd=DS001&apiId=2019018)
- [OpenDART 전체 재무제표](https://opendart.fss.or.kr/guide/detail.do?apiGrpCd=DS003&apiId=2019020)
- [OpenAI MCP 설정](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)

MIT License