🏢 한국 기업정보 조회 MCP 서버

DART API를 활용한 고성능 MCP (Model Context Protocol) 서버입니다.

AI 에이전트(Claude Desktop, Cursor 등)가 실시간으로 한국 상장기업의 재무제표, 공시정보, 임원정보, 지분구조 등을 조회하고 분석할 수 있도록 합니다.

✨ 주요 기능

📊 기업 정보 조회 (DART API)

기능	설명
기업 검색	회사명으로 기업 검색 및 기본정보 조회
기업 기본정보	회사명, 대표자명, 설립일, 본사주소 등 기본정보 조회
재무제표 조회	손익계산서, 재무상태표, 현금흐름표
재무 추이 분석	최근 5-10년 재무제표 추이 분석
공시정보 조회	최근 공시 목록 및 상세 내용
주요사항보고서	임원변경, 자본금변경 등 주요사항 조회
임원정보 조회	임원명, 직책, 보수 등 임원정보 조회
지분보고서	주주명, 보유지분, 비율 등 지분구조 조회
공시원문 다운로드	공시보고서 원문 XML/PDF 다운로드 및 파싱

🚀 성능 최적화

전략적 캐싱: 기업정보 데이터를 24시간 캐싱하여 API 호출 최소화
빠른 응답 속도: 캐시 기반 즉시 응답
안정적인 운영: 에러 핸들링 및 로깅 시스템
API 키 우선순위: 메인 서버에서 받은 키 → .env 파일 (로컬 개발용)

🎯 활용 사례

투자사/VC

투자 검토: 스타트업 재무제표 분석 및 성장성 평가
기업 가치 평가: 재무 추이 분석을 통한 가치 산정
경쟁사 분석: 여러 기업의 재무제표 비교 분석

B2B 영업팀

고객사 분석: 잠재 고객의 재무 상태 파악
영업 전략 수립: 기업 정보 기반 맞춤형 영업 전략
신용도 확인: 거래 전 재무 건전성 확인

컨설팅 회사

기업 분석 리포트: 재무제표, 공시정보 자동 수집 및 분석
경쟁사 비교: 여러 기업의 재무 지표 비교
시장 분석: 업종별 기업 재무 현황 분석

스타트업/개발자

경쟁사 모니터링: 경쟁사의 재무 현황 추적
투자 유치 준비: 재무제표 분석을 통한 투자 자료 준비
기업 리서치: 잠재 파트너사 정보 수집

🛠️ 기술 스택

MCP Framework: FastMCP
Data Validation: Pydantic
HTTP Client: Requests
Caching: cachetools (TTL 캐시)
Async Processing: asyncio
Environment: Python-dotenv

📦 설치 및 설정

1) 의존성 설치

pip install -r requirements.txt

💡 uv를 사용하는 경우: uv sync

2) DART API 키 발급 (무료, 즉시)

전자공시시스템 Open DART 방문
회원가입 및 로그인
인증키 신청/관리 메뉴에서 인증키 발급
즉시 발급 (무료)

💡 무료이며, 일일 API 호출 제한이 충분히 넉넉합니다!

3) 환경 변수 설정

프로젝트 루트에 .env 파일을 생성하고 API 키를 설정합니다:

cp env.example .env

.env 파일 내용:

DART_API_KEY=your_dart_api_key_here LOG_LEVEL=INFO PORT=8097

4) 서버 실행

MCP 서버 모드 (stdio)

python -m src.main

HTTP 서버 모드

HTTP_MODE=1 python src/main.py

또는

export HTTP_MODE=1 python src/main.py

HTTP 서버는 기본적으로 http://localhost:8097에서 실행됩니다.

🐳 Docker 실행

# 이미지 빌드 docker build -t company-info-mcp:latest . # 컨테이너 실행 docker run --rm \ -e DART_API_KEY=your_dart_api_key_here \ -p 8097:8097 \ company-info-mcp:latest

🔌 Claude Desktop 연동

설정 파일 위치

Windows: %APPDATA%\Claude\claude_desktop_config.json
Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

설정 예시

{ "mcpServers": { "company-info": { "command": "python", "args": ["-m", "src.main"], "cwd": "C:/Users/사용자명/Desktop/company-info-mcp", "env": { "DART_API_KEY": "your_dart_api_key_here" } } } }

⚠️ 중요: cwd 경로를 실제 프로젝트 경로로 변경하세요!

사용 방법

Claude Desktop 재시작 후 Claude에게 질문:

"삼성전자 재무제표 분석해줘"
"네이버 최근 공시 확인해줘"
"카카오뱅크 투자 검토해줘"
"네이버, 카카오, 라인 재무 비교해줘"

🧰 사용 가능한 도구 (Tools)

1. `health`

서비스 상태 및 API 키 설정 확인

파라미터: 없음 (또는 arguments.env.DART_API_KEY)

반환 예시:

{ "status": "ok", "message": "정상", "service": "Korean Company Information MCP Server (Free Version)", "environment": { "dart_api_key": "설정됨", "dart_key_preview": "abc123...", "key_source": "arguments.env" } }

2. `search_company_tool`

기업을 회사명으로 검색

파라미터:

query (string, 필수): 검색할 회사명 (예: '삼성전자', '네이버')

반환: 검색된 기업 목록 (기업 고유번호 포함)

3. `get_financial_statement_tool`

기업의 재무제표 조회

파라미터:

corp_code (string, 선택): 기업 고유번호
company_name (string, 선택): 회사명 (corp_code 또는 company_name 중 하나 필수)
bsns_year (string, 선택): 사업연도 (YYYY 형식, 기본값: 최근 연도)
reprt_code (string, 선택): 보고서 코드 (11011: 사업보고서, 11013: 분기보고서, 기본값: 11011)

반환: 재무제표 정보 (손익계산서, 재무상태표, 현금흐름표)

4. `analyze_financial_trend_tool`

기업의 재무 추이 분석 (최근 N년)

파라미터:

corp_code (string, 필수): 기업 고유번호
years (integer, 선택): 분석할 연수 (기본값: 5, 최대: 10)

반환: 재무 추이 분석 결과 (최근 N년 재무제표 데이터)

5. `get_public_disclosure_tool`

기업의 공시정보 조회

파라미터:

corp_code (string, 필수): 기업 고유번호
bgn_de (string, 선택): 시작일 (YYYYMMDD 형식, 기본값: 최근 1개월)
end_de (string, 선택): 종료일 (YYYYMMDD 형식, 기본값: 오늘)
page_no (integer, 선택): 페이지 번호 (기본값: 1)
page_count (integer, 선택): 페이지당 건수 (기본값: 10, 최대: 100)

반환: 공시정보 목록

6. `get_company_overview_tool`

기업의 기본정보 조회

파라미터:

corp_code (string, 선택): 기업 고유번호
company_name (string, 선택): 회사명 (corp_code 또는 company_name 중 하나 필수)

반환: 기업 기본정보 (회사명, 대표자명, 설립일, 본사주소 등)

7. `get_major_report_tool`

주요사항보고서 조회

파라미터:

corp_code (string, 선택): 기업 고유번호
company_name (string, 선택): 회사명
bgn_de (string, 선택): 시작일 (YYYYMMDD 형식, 기본값: 최근 1개월)
end_de (string, 선택): 종료일 (YYYYMMDD 형식, 기본값: 오늘)

반환: 주요사항보고서 목록 (임원변경, 자본금변경 등)

8. `download_disclosure_document_tool`

공시원문 다운로드

파라미터:

rcept_no (string, 필수): 접수번호 (공시정보에서 얻을 수 있음)
file_format (string, 선택): 파일 형식 ("xml" 또는 "pdf", 기본값: "xml")

반환: 공시원문 데이터 (XML은 파싱된 데이터 포함, PDF는 base64 인코딩)

9. `get_executives_tool`

기업의 임원정보 조회

파라미터:

corp_code (string, 선택): 기업 고유번호
company_name (string, 선택): 회사명 (corp_code 또는 company_name 중 하나 필수)

반환: 임원정보 목록 (임원명, 직책, 보수 등)

10. `get_shareholders_tool`

지분보고서 조회

파라미터:

corp_code (string, 선택): 기업 고유번호
company_name (string, 선택): 회사명
bsns_year (string, 선택): 사업연도 (YYYY 형식, 기본값: 최근 연도)
reprt_code (string, 선택): 보고서 코드 (11011: 사업보고서, 11013: 분기보고서, 기본값: 11011)

반환: 지분보고서 (주주명, 보유지분, 비율 등)

💡 사용 예시

예시 1: 기업 재무제표 분석

사용자: "삼성전자 재무제표 분석해줘"

AI 에이전트가 수행하는 작업:

search_company_tool(query="삼성전자") 호출 → corp_code 확인
get_financial_statement_tool(company_name="삼성전자", bsns_year="2024") 호출
재무제표 분석 및 요약 제공

예시 2: 재무 추이 분석

사용자: "네이버 최근 5년 재무 추이 분석해줘"

AI 에이전트가 수행하는 작업:

기업 검색 → corp_code 확인
analyze_financial_trend_tool(corp_code="...", years=5) 호출
최근 5년 매출, 영업이익, 순이익 추이 분석
성장성 평가 및 그래프 생성

예시 3: 투자 검토

사용자: "카카오뱅크 투자 검토해줘"

AI 에이전트가 수행하는 작업:

search_company_tool(query="카카오뱅크") - 회사 검색
get_company_overview_tool(company_name="카카오뱅크") - 기본정보 확인
analyze_financial_trend_tool(corp_code="...", years=3) - 최근 3년 재무 추이
get_executives_tool(company_name="카카오뱅크") - 임원진 확인
get_shareholders_tool(company_name="카카오뱅크") - 지분구조 확인
get_public_disclosure_tool(corp_code="...") - 최근 공시 확인
종합 투자 의견 제시

예시 4: 경쟁사 비교

사용자: "네이버, 카카오, 라인 재무 비교해줘"

AI 에이전트가 수행하는 작업:

각 회사별로 analyze_financial_trend_tool 호출
매출, 영업이익, 순이익 추이 비교
성장률 계산 및 비교표 생성
get_shareholders_tool로 지분구조 비교

예시 5: 공시 원문 상세 분석

사용자: "삼성전자 최근 공시 중 중요한 것 하나 상세 분석해줘"

AI 에이전트가 수행하는 작업:

get_public_disclosure_tool(company_name="삼성전자", page_count=10) - 최근 공시 목록
공시 제목 분석하여 중요 공시 선택
download_disclosure_document_tool(rcept_no="...", file_format="xml") - 공시원문 다운로드
XML 파싱된 데이터 분석
핵심 내용 요약 및 의견 제시

🌐 HTTP API 엔드포인트

HTTP 서버 모드로 실행 시 다음 엔드포인트를 사용할 수 있습니다:

`GET /health`

서비스 상태 확인

응답 예시:

{ "status": "ok", "message": "정상", "service": "Korean Company Information MCP Server (Free Version)", "environment": { "dart_api_key": "설정됨", "key_source": ".env file" } }

`POST /health`

서비스 상태 확인 (env 포함 가능)

요청 본문:

{ "env": { "DART_API_KEY": "your_api_key_here" } }

`GET /tools`

사용 가능한 도구 목록 조회

응답: 도구 목록 배열

`POST /tools/{tool_name}`

도구 호출

요청 예시:

{ "query": "삼성전자", "env": { "DART_API_KEY": "your_api_key_here" } }

🔑 API 키 우선순위

MCP 서버는 다음 순서로 API 키를 찾습니다:

우선순위 1: arguments.env.DART_API_KEY (메인 서버에서 받은 키)
우선순위 2: .env 파일의 DART_API_KEY (로컬 개발용)
둘 다 없으면: Health 체크에서 "등록된 키가 없습니다" 반환

이를 통해:

프로덕션: 메인 서버에서 각 사용자별 키를 전달받아 사용
로컬 개발: .env 파일에 키를 설정하여 개발

📁 프로젝트 구조

company-info-mcp/ ├── src/ │ ├── __init__.py │ ├── main.py # MCP 서버 메인 파일 │ └── tools.py # 기업정보 API 호출 도구 ├── .env # 환경 변수 파일 (API 키 등) - .gitignore에 포함 ├── env.example # 환경 변수 예시 파일 ├── requirements.txt # Python 의존성 ├── pyproject.toml # 프로젝트 설정 ├── Dockerfile # Docker 이미지 빌드 파일 ├── DEVELOPMENT_GUIDE.md # 개발 가이드 (DART API 그룹별 기능) └── README.md # 프로젝트 문서 (이 파일)

⚠️ 제한사항

무료 버전의 한계

상장기업만 가능: DART API는 상장기업 정보만 제공 (비상장 기업 불가)
사업자등록정보 없음: 기본 사업자 정보는 유료 API 필요
신용정보 없음: 신용등급은 유료 API 필요

API 사용 제한

DART API: 일일 호출 제한 있음 (보통 충분함)
API 키는 무료로 발급 가능

🐛 문제 해결

"API 키가 설정되지 않았습니다" 오류

원인: DART_API_KEY 환경 변수가 설정되지 않음

해결:

.env 파일 확인
DART_API_KEY=your_key_here 형식으로 설정되어 있는지 확인
또는 메인 서버에서 arguments.env.DART_API_KEY로 전달

"DART API 오류" 메시지

원인: API 키가 잘못되었거나 기업을 찾을 수 없음

해결:

API 키가 올바른지 확인
상장기업인지 확인 (비상장 기업은 지원 안 됨)
회사명 정확히 입력 (예: "삼성전자" O, "삼성" X)

Claude Desktop에서 도구가 보이지 않음

해결:

claude_desktop_config.json 파일 경로 확인
JSON 형식이 올바른지 확인 (콤마, 따옴표 등)
cwd 경로를 실제 프로젝트 경로로 변경
Claude Desktop 완전 종료 후 재시작
로그 파일 확인 (Windows: %APPDATA%\Claude\logs)

📚 개발 가이드

DART API의 각 그룹별 기능과 추가 개발 방법은 DEVELOPMENT_GUIDE.md를 참고하세요.

구현 상태

DS001: 공시정보 조회 (✅ 구현 완료)
DS002: 재무정보 조회 (✅ 구현 완료)
DS003: 기업개황 정보 (✅ 주요 기능 구현 완료)
DS004: 공시원문 다운로드 (✅ 구현 완료)
DS005: 주요사항보고서 (✅ 구현 완료)
DS006: 기타 정보 (✅ 주요 기능 구현 완료)

🤝 기여 및 문의

이슈: GitHub Issues
문의: company-info-mcp@example.com
문서: https://github.com/your-repo/company-info-mcp

📄 라이선스

MIT License

Made with ❤️ for Korean Business Professionals

DART API를 활용하여 개발되었습니다.

🏢 한국 기업정보 조회 MCP 서버

✨ 주요 기능

📊 기업 정보 조회 (DART API)

🚀 성능 최적화

🎯 활용 사례

투자사/VC

B2B 영업팀

컨설팅 회사

스타트업/개발자

🛠️ 기술 스택

📦 설치 및 설정

1) 의존성 설치

2) DART API 키 발급 (무료, 즉시)

3) 환경 변수 설정

4) 서버 실행

MCP 서버 모드 (stdio)

HTTP 서버 모드

🐳 Docker 실행

🔌 Claude Desktop 연동

설정 파일 위치

설정 예시

사용 방법

🧰 사용 가능한 도구 (Tools)

1. health

2. search_company_tool

3. get_financial_statement_tool

4. analyze_financial_trend_tool

5. get_public_disclosure_tool

6. get_company_overview_tool

7. get_major_report_tool

8. download_disclosure_document_tool

9. get_executives_tool

10. get_shareholders_tool

💡 사용 예시

예시 1: 기업 재무제표 분석

예시 2: 재무 추이 분석

예시 3: 투자 검토

예시 4: 경쟁사 비교

예시 5: 공시 원문 상세 분석

🌐 HTTP API 엔드포인트

GET /health

POST /health

GET /tools

POST /tools/{tool_name}

🔑 API 키 우선순위

📁 프로젝트 구조

⚠️ 제한사항

무료 버전의 한계

API 사용 제한

🐛 문제 해결

"API 키가 설정되지 않았습니다" 오류

"DART API 오류" 메시지

Claude Desktop에서 도구가 보이지 않음

📚 개발 가이드

구현 상태

🤝 기여 및 문의

📄 라이선스

Related Resources

New MCP Servers

MCP directory API

1. `health`

2. `search_company_tool`

3. `get_financial_statement_tool`

4. `analyze_financial_trend_tool`

5. `get_public_disclosure_tool`

6. `get_company_overview_tool`

7. `get_major_report_tool`

8. `download_disclosure_document_tool`

9. `get_executives_tool`

10. `get_shareholders_tool`

`GET /health`

`POST /health`

`GET /tools`

`POST /tools/{tool_name}`