Open Esg Korea

open-esg-korea

한국 상장사 ESG 데이터를 AI 에게 바로 물어볼 수 있게 하는 MCP 서버

이렇게 물으면 됩니다.

「삼성전자 ESG 등급 어때?」
「현대자동차 온실가스 배출량 얼마야?」
「KB금융 SR보고서 목차랑 금융배출량 알려줄래?」

Stars License: Apache 2.0 Release Python 3.10+ MCP Tools Sponsor

English

설치 · 이렇게 물어보세요 · 12가지 기능 · 읽을 때 주의 · 라이선스 · 개발자용

KRX ESG 포털·GIR 온실가스종합정보센터·KIND 공시에 흩어진 기관별 ESG 등급 · 온실가스 배출량 · 지배구조 지표 · 보고서 원문을 AI 클라이언트(Claude Desktop, Cursor 등)가 자연어로 바로 물을 수 있게 하는 게이트웨이입니다.

형제 프로젝트 open-proxy-mcp(DART 공시 분석)와 같은 구조입니다.

flowchart LR
    A["KRX ESG 포털<br/>5개 기관 등급 · 지배구조 핵심지표"] --> S
    B["KIND 공시<br/>지배구조보고서 · 지속가능경영보고서 PDF 데이터 추출"] --> S
    C["GIR<br/>온실가스 명세서 · 배출권거래제"] --> S
    S["open-esg-korea<br/>MCP 서버 · 도구 12개<br/>값마다 출처 · 연도 · 이용조건"] --> D["Claude Desktop · ChatGPT<br/>「삼성전자 ESG 등급 어때?」"]

세 곳 다 API 키 없이 조회됩니다. 등급은 저장하지 않고 물을 때마다 실시간으로 가져옵니다.

[!IMPORTANT] 코드는 Apache-2.0 입니다 — 상업 이용을 포함해 자유롭게 쓰시고, 출처만 밝혀 주세요. 다만 이 서버가 읽어오는 등급 데이터는 그 라이선스에 들어가지 않습니다. 등급은 각 평가기관의 저작물이고 다섯 기관 모두 대외 공개를 금지합니다. 이 서버는 값을 저장하지 않고 물을 때마다 실시간으로 가져오지만, 받아본 값을 수집·재배포하는 것은 별개 문제입니다. 라이선스 절을 꼭 읽어 주세요.

🚀 5분 설치

파이썬을 깔고, 파일 하나 받아서 끌어다 놓으면 끝입니다. 명령어를 외울 일도, 개발도구도, API 키도 없습니다.

_{필요한 것 — Claude Desktop(무료)과 Claude 계정. 무료 플랜으로도 되지만 대화량이 빠듯합니다. 회사 계정은 관리자가 확장 설치를 막아 뒀을 수 있습니다. ChatGPT 는 → ChatGPT에 연결하기}

1단계 — 파이썬 설치하기

python.org/downloads 에서 받아 설치합니다. 이미 있으면 건너뛰세요.

[!IMPORTANT] Windows 는 설치 화면 맨 아래 「Add python.exe to PATH」를 꼭 켜세요. 안 켜면 설치해도 못 찾습니다. 놓쳤다면 설치 파일을 다시 실행해 Modify 로 고칩니다.

터미널(Windows 는 명령 프롬프트)을 새로 열어 확인합니다.

python3 --version     # Windows 는  python --version

_{확장 안에도 파이썬이 들어 있지만, 환경에 따라 어긋나는 일이 있어 미리 깔아두는 쪽이 확실합니다.}

2단계 — 내 컴퓨터에 맞는 파일 받기

_{내 Mac 이 어느 쪽인지 모르겠다면 터미널에 uname -m — arm64 면 Apple 실리콘, x86_64 면 인텔입니다 (애플 메뉴 → 「이 Mac에 관하여」의 칩 항목으로도 볼 수 있습니다). 잘못 받아도 확장이 어느 파일을 받아야 하는지 알려 줍니다.}

_{리눅스용 번들은 아직 없습니다 — 개발자용으로 연결하세요.}

3단계 — Claude Desktop 에 끌어다 놓기

1. Claude Desktop 을 엽니다 — 없으면 claude.com/download 에서 받으세요 (무료)
2. 설정 → 확장(Extensions) 으로 갑니다
3. 받은 .mcpb 파일을 창 안으로 끌어다 놓습니다 (또는 「확장 프로그램 설치」로 파일 선택)
4. 설치를 누릅니다

[!NOTE] 「이 확장 프로그램이 컴퓨터의 모든 항목에 액세스할 수 있습니다 · 개발자 정보를 Anthropic 에서 확인하지 않았습니다」라는 빨간 경고가 뜹니다. Anthropic 이 심사한 공식 확장이 아니라는 뜻이고, 개인이 만든 확장은 전부 이렇게 표시됩니다. 안에 무엇이 들었는지는 scripts/build_mcpb.py 에 전부 적혀 있고, 압축을 풀면 lib/ 아래 파이썬 코드를 그대로 읽을 수 있습니다. 번들마다 어느 커밋으로 만들었는지 적힌 BUILD_INFO.txt 가 들어 있습니다.

[!TIP] 도구를 쓸 때마다 승인 창이 뜨는 게 번거롭다면, 확장 목록에서 한국 상장사 ESG 정보 → 구성 을 열고 항상 승인을 켜 두세요. 그 뒤로는 승인 창 없이 바로 답합니다.

4단계 — 물어보기

Claude 에게 그냥 한국어로 물어보세요.

삼성전자 ESG 등급 알려줘

5개 기관 등급표가 출처·연도·이용조건과 함께 나오면 성공입니다. API 키를 넣는 단계는 없습니다.

ChatGPT 를 쓰신다면

.mcpb 는 Claude Desktop 전용 형식입니다. ChatGPT 쪽에서는 Codex(CLI · IDE 확장 · Codex 앱)에 MCP 서버로 붙이며, 역시 명령 한 줄입니다. Codex 는 ChatGPT 무료 플랜에도 포함됩니다.

→ ChatGPT에 연결하기

무엇이 들어 있나

💬 이렇게 물어보세요

설치하고 나면 도구 이름을 외울 필요가 없습니다. 하고 싶은 말을 그냥 하면 Claude 가 알아서 고릅니다. 아래는 실제로 되는 질문들입니다.

알아두면 편한 것

• 회사 이름은 통칭도 됩니다 — 「현대차」「에스케이하이닉스」「삼성SDS」「케이티앤지」 다 알아듣습니다. 별칭이 쓰이면 응답에 그 사실이 적힙니다.
• - 는 「미평가」입니다 — 0 점도, 나쁜 등급도 아닙니다. 자료가 없으면 그렇다고 말합니다.
• 코스닥은 등급표까지만 나옵니다 — 포털이 보고서·지배구조 화면에는 유가증권만 싣습니다.
• 모든 값에 출처·연도·이용조건이 붙습니다. 응답의 license 를 지우지 마세요.

도구 (12개)

읽을 때 주의

라이선스

코드는 Apache License 2.0 입니다. 상업적 이용을 포함해 자유롭게 쓰고, 고치고, 배포하고, 이걸로 제품을 만들어 파셔도 됩니다. 조건은 하나 — 출처를 밝히는 것입니다.

구체적으로는 재배포본에 LICENSE 와 NOTICE 를 함께 두고, open-esg-korea 에서 파생했음을 밝히면 됩니다. 파일을 고쳤다면 고쳤다고 적어 주세요. 그게 전부입니다.

[!WARNING] 이 라이선스는 소프트웨어에 대한 것이지, 소프트웨어가 읽어오는 데이터에 대한 것이 아닙니다.

ESG 등급은 각 평가기관의 저작물이고 조건이 기관마다 다릅니다 — KCGS·MSCI 는 「내부 용도로만」, 서스틴베스트·S&P 는 「사전 서면허가 없이 어떤 형태의 복제도 불가」, 한국ESG연구소는 「사전 서면동의 없이 복제·전송·인용·배포 불가」입니다. 다섯 곳 모두 대외 공개는 안 됩니다.

코드를 상업적으로 써도 된다는 것이 등급을 수집·저장·재배포·재판매해도 된다는 뜻이 아닙니다. 공개 엔드포인트로 띄우거나 등급 자체로 상품을 만들려면 각 기관에 먼저 문의해야 합니다.

그래서 이 서버는 등급을 실시간으로만 가져오고 DB·저장소·로그 어디에도 남기지 않으며(캐시는 메모리뿐), 값마다 그 기관의 고지와 원문 주소를 붙여 돌려줍니다. 응답의 license 칸을 지우지 마세요. 공시 원문은 제출 회사의 문서이고, 온실가스 수치는 GIR 공개정보로 각자의 조건을 따릅니다.

자세한 것은 NOTICE 에 있습니다.

개발자용

준비물 — 1단계의 파이썬과 uv (curl -LsSf https://astral.sh/uv/install.sh | sh, Windows 는 설치 안내).

uv sync
uv run python -m open_esg_korea                     # http://localhost:8000/mcp
uv run python -m open_esg_korea --transport stdio   # Claude Desktop 로컬 연결

Claude Desktop claude_desktop_config.json 예:

{"mcpServers": {"open-esg-korea": {"command": "uv", "args": ["run", "--directory", "/path/to/open-esg-korea",
  "python", "-m", "open_esg_korea", "--transport", "stdio"]}}}

확장(.mcpb) 직접 만들기

uv run python scripts/build_mcpb.py                        # 지금 이 기계용 하나
uv run python scripts/build_mcpb.py --target macos-arm64   # 하나 지정
uv run python scripts/build_mcpb.py --target all --check   # 셋 다 + 만든 뒤 실제로 실행해 확인

--check 는 만든 번들을 풀어서 매니페스트에 적힌 명령 그대로 띄우고 stdio 핸드셰이크로 도구 12개가 응답하는지 확인합니다 — 「빌드는 됐는데 안 열린다」를 막습니다. 이 기계에서 못 돌리는 타깃은 건너뜁니다.

테스트

uv sync --dev && uv run pytest -q     # network 0

문서

• ChatGPT에 연결하기 — Codex(CLI·IDE·앱)에 MCP 서버로 붙이는 법
• MCP 초안·로드맵 — 데이터 소스 지도, 엔드포인트 확인 내용, Phase 별 근거
• 실측 노트 — 두드려 보고 나서야 알게 된 것들(DART 링크가 다른 회사를 연다, 자간 공백이 PDF 에 박혀 있다, 벤치마크 1위 파서가 우리 수치표를 못 잡는다…)

스냅샷 갱신

실서버 점검

python scripts/probe_krx.py 005930 2025   # 포털 응답 스키마가 바뀌었는지
uv run python scripts/smoke_kind.py       # KIND 공시 원문(지배구조·지속가능)이 아직 읽히는지