Submit
hwibalyu

edinet-mcp

Community hwibalyu
Updated

edinet-mcp

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는 저장소에 커밋하지 않도록 유지하세요.

MCP Server · Populars

MCP Server · New