open-esg-korea

open-esg-korea는 한국 상장사의 ESG 정보를 AI 클라이언트에서 자연어로 바로 물어볼 수 있게 해 주는 MCP(Model Context Protocol) 서버다. 증권사 애널리스트가 만들었으며, 형제 프로젝트 open-proxy-mcp(DART 공시 분석)와 같은 구조를 쓴다. ■ 데이터 출처와 방식 KRX ESG 포털의 5개 기관(KCGS·MSCI·한국ESG연구소·S&P·서스틴베스트) ESG/E/S/G 등급과 기업지배구조 핵심지표, KIND 공시의 기업지배구조보고서·지속가능경영보고서 원문(PDF 본문 추출), GIR 온실가스종합정보센터의 온실가스 명세서·배출권거래제 정보를 한 곳에서 다룬다. 세 곳 모두 조회에 API 키가 필요 없고, 등급은 저장하지 않고 질문할 때마다 실시간으로 가져온다. 모든 값에 출처·연도·이용조건이 함께 붙는다. ■ 설치 릴리스에서 플랫폼에 맞는 .mcpb 파일(macOS Apple Silicon·Intel 약 40~44MB, Windows x64 약 43MB)을 받아 Claude Desktop의 설정 → 확장 화면에 끌어다 놓으면 끝난다. 파이썬 런타임이 번들로 들어 있어 파이썬이나 개발도구, API 키가 필요 없다. 리눅스용 번들은 아직 없고, ChatGPT에서는 Codex(CLI·IDE 확장·앱)에 MCP 서버로 연결하는 경로를 안내한다. 설치 파일 안에는 런타임, 의존성(mcp·httpx·pypdfium2·pdfplumber), 서버 본체, 매니페스트, 빌드 정보가 들어 있다. ■ 도구 12개 company(회사명·종목코드 조회), esg_ratings(기관별 등급과 같은 기관 안에서의 분포), sustainability_reports(보고서 목록·검증기관·첨부 PDF 주소), sustainability_report_text(PDF 본문 키워드 검색·발췌·쪽 보기), governance_indicators(핵심지표 15개 O/X·준수율), governance_policies(정책 74개 항목), governance_report(보고서 원문, 세부원칙 28개 답변·미준수 사유), esg_disclosures(공시 이력), esg_screener(유가증권 전체 등급 스크리너, 2025년 795사 기준), ghg_emissions(회사별 배출량·5년 추이·배출권 할당 대비), ghg_industry(지정업종·법인별 배출량 순위), ghg_national_inventory(1990년~ 국가 인벤토리 시계열). ■ 읽을 때 주의 기관마다 등급 스케일이 달라 나란히 비교하지 않도록 안내한다(KCGS S~D, MSCI AAA~CCC, S&P 0-100점, 서스틴베스트 AA~E). '-'는 미평가이며 0점이나 나쁜 등급이 아니다. 등급이 6~7단계뿐이라 동점이 많아 '상위 N%'는 만들지 않고, 같은 기관 안에서 세어 답한다. 업종 체계는 GICS 산업군 25개, 포털 업종 21개, GIR 지정업종으로 서로 다르다. 코스닥은 등급표까지만 나온다. 지배구조는 KRX 집계와 회사가 직접 쓴 원문 두 층으로 답하며, 원문을 못 읽으면 '0개 준수'가 아니라 '읽지 못함'으로 구분한다. 온실가스는 값보다 범위(경계·Scope 2 방식·NF₃ 포함 여부)를 먼저 제시하고, GIR에 없으면 no_data로 표시한다. 보고서 수치의 자동 표 추출은 실험적(값 보존 97.4%, 의심 칸은 경고)이며, PDF 검색은 자간 공백을 무시하고 이미지 PDF는 OCR 없이 읽지 못한다. 접수번호는 KIND 번호라 DART 뷰어와 다르다. ■ 라이선스 주의 코드는 Apache-2.0으로 상업적 이용을 포함해 자유롭게 쓰고 고치고 배포할 수 있으며, 조건은 출처 표시다. 다만 이 라이선스는 서버가 읽어오는 데이터에는 적용되지 않는다. ESG 등급은 각 평가기관의 저작물이고 다섯 기관 모두 대외 공개를 금지하므로, 등급을 수집·저장·재배포·재판매하거나 등급 자체로 상품을 만들려면 각 기관에 먼저 문의해야 한다. 그래서 서버는 등급을 메모리 캐시 외에 남기지 않고 응답의 license 칸을 지우지 말 것을 요청한다. ■ 개발자용 uv로 의존성을 설치한 뒤 python -m open_esg_korea(HTTP, localhost:8000/mcp) 또는 --transport stdio로 실행하고, claude_desktop_config.json에 등록해 로컬 연결할 수 있다. scripts/build_mcpb.py로 플랫폼별 확장을 직접 빌드하고 --check로 매니페스트대로 기동해 도구 12개가 응답하는지 확인한다. 테스트는 네트워크 없이 pytest로 돌아간다. GICS 분류·상장사 명부 스냅샷 갱신 스크립트와 워크플로, KRX 응답 스키마·KIND 공시 접근을 점검하는 probe/smoke 스크립트, MCP 초안·실측 노트 문서도 함께 제공한다.