edinet-mcp

edinet-mcp는 EDINET API v2를 MCP 서버로 감싼 프로젝트입니다.
다운로드한 뒤 Python 환경만 준비하면 MCP 클라이언트에서 바로 공시 조회, 문서 다운로드, 본문 텍스트 추출을 사용할 수 있습니다.

무엇을 할 수 있나요?

• 특정 날짜의 공시 목록 조회

• 기간별 공시 검색

• docID 기준 원문(PDF/ZIP) 다운로드

• PDF, XBRL ZIP, CSV ZIP의 텍스트 추출

• EDINET/Fund 코드리스트 조회 및 검색

• 자연어 질문 기반 후보 문서 탐색

사용 전 준비

• Python 3.10 이상

• EDINET API Key

설치

git clone <your-repo-url>
cd edinet-mcp

python3 -m venv env
./env/bin/pip install -r requirements.txt
cp .env.example .env

.env 파일에서 EDINET_API_KEY를 실제 키로 바꿔주세요.

실행

프로젝트 루트에서 아래처럼 실행하면 됩니다.

./env/bin/python src/server.py

이 서버는 .env를 현재 작업 디렉터리 기준으로 읽기 때문에, 프로젝트 루트에서 실행하는 것이 안전합니다.

MCP에 등록하기

예시: ~/.config/opencode/opencode.json

{
  "mcp": {
    "edinet-mcp": {
      "type": "local",
      "enabled": true,
      "command": [
        "/ABSOLUTE/PATH/edinet-mcp/env/bin/python",
        "/ABSOLUTE/PATH/edinet-mcp/src/server.py"
      ],
      "cwd": "/ABSOLUTE/PATH/edinet-mcp"
    }
  }
}

중요한 점:

• command는 문자열 하나가 아니라 문자열 배열이어야 합니다.

• cwd를 프로젝트 루트로 지정해야 .env를 안정적으로 읽습니다.

자주 쓰는 도구

• edinet_health_check: API 키와 연결 상태 확인

• edinet_list_documents: 특정 날짜 공시 목록 조회

• edinet_search_documents: 기간 조건으로 공시 검색

• edinet_get_latest_documents: 최근 며칠치 공시 조회

• edinet_download_document: 문서 원본 저장

• edinet_read_document_text: 문서 본문 텍스트 추출

• edinet_search_code_list: 회사명이나 코드 검색

• edinet_answer_question: 자연어 질문으로 후보 문서와 근거 찾기

환경변수

• EDINET_API_KEY: 필수

• EDINET_API_BASE_URL: 기본값 https://api.edinet-fsa.go.jp

• EDINET_USER_AGENT: 기본값 edinet-mcp/0.1

• EDINET_TIMEOUT_SECONDS: 기본값 30

• EDINET_CACHE_DIR: 기본값 .cache

• EDINET_DOWNLOAD_DIR: 기본값 downloads

사용 흐름 예시

보통은 아래 순서로 사용하면 됩니다.

1. edinet_health_check로 연결 확인

2. edinet_search_documents 또는 edinet_get_latest_documents로 후보 찾기

3. 필요한 문서의 docID 확인

4. edinet_download_document 또는 edinet_read_document_text 호출

질문형 탐색이 필요하면 edinet_answer_question을 바로 사용해도 됩니다.

문제 해결

• EDINET_API_KEY is not set

  • .env가 프로젝트 루트에 있는지 확인

  • 키 앞뒤 공백이 없는지 확인

• 401 또는 인증 오류

  • API 키가 유효한지 확인

• 문서가 안 내려받아짐

  • doc_id, doc_type 값이 맞는지 확인

• 검색 범위가 너무 넓어 느림

  • 날짜 범위를 더 짧게 나눠서 조회

참고

• 다운로드 파일은 기본적으로 downloads/ 아래에 저장됩니다.

• 캐시 파일은 기본적으로 .cache/ 아래에 저장됩니다.

• .env는 저장소에 커밋하지 않도록 유지하세요.