korea-public-data-mcp

Dies ist ein MCP-Server, der es Claude ermöglicht, direkt auf koreanische öffentliche Daten (금융감독원 OpenDART, 한국은행 ECOS, 통계청 KOSIS, 공공데이터포털) zuzugreifen und Finanz‑, Wirtschafts‑ und Statistikzahlen nicht durch Schätzung, sondern basierend auf tatsächlichen API‑Antworten zu beantworten.

Analog zu MCPs, die DART‑Elektronikbekanntmachungsdaten nutzen, um Finanzauskunftsfragen zu beantworten, kann Claude bei Fragen wie „Wie hoch war der Umsatz dieser Firma im letzten Jahr?“, „Gib mir den aktuellen Leitzinstrend“ oder „Wie hoch ist die Arbeitslosenquote in Korea?“ die Werkzeuge dieses Servers aufrufen und mit den neuesten Zahlen antworten.

Der Name ist vorläufig als korea-public-data-mcp festgelegt. Wenn Sie das Repository auf GitHub hochladen, können Sie den Namen frei ändern, ohne dass dies die Funktionsweise des Codes beeinträchtigt.

Warum wurde es so gemacht? (Entwurfsprinzipien)

Der Server wurde unter Einhaltung der drei vom Verantwortlichen geforderten Einschränkungen entwickelt.

1. Keine LLM‑/externen Kosten – Dieser Server „holt nur“ Daten. Er ruft intern kein LLM auf und verwendet keine kostenpflichtigen APIs. Die eigentliche Schlussfolgerung/Zusammenfassung übernimmt Claude, der diesen MCP aufruft. Die Betriebskosten des Servers sind daher praktisch null (abgesehen von Strom‑/Serverressourcen).

2. Verhinderung von API‑Sperren (IP‑Ban) – Staatliche öffentliche APIs sperren bei Überschreitung der Aufrufbegrenzung pro Sekunde/Tag vorübergehend. Deshalb:

   • Vor jedem API‑Aufruf wird eine Anfragenbegrenzung pro Sekunde (Token‑Bucket) eingebaut, um die Geschwindigkeit selbst zu drosseln.

   • Bei wiederholten gleichen Anfragen wird der Arbeitsspeicher‑Cache genutzt; große statische Dateien wie die DART‑Firmenliste werden mit einem Festplatten‑Cache (standardmäßig 7 Tage) vor erneutem Herunterladen geschützt.

   • Konten und Zeiträume werden nicht einzeln aufgerufen, sondern tabellen‑ und zeitraumweise auf einmal abgerufen (z. B. werden bei Finanzausweisen alle Konten mit einem Aufruf pro Firma abgerufen, Statistiken werden für den gesamten Start‑ bis Endzeitraum auf einmal abgefragt).

   • Bei APIs, die Batch‑Verarbeitung unterstützen (z. B. Geschäftsstatusabfrage), werden maximal 100 Fälle in einem Aufruf gebündelt gesendet.

   • Bei 429‑/5xx‑Antworten wird mit exponentiellem Backoff maximal 3‑mal wiederholt.

3. Jeder führt Docker lokal aus – Es wird kein separater Server gestartet; jedes Teammitglied startet lokal docker build + docker run und verbindet es mit seinem eigenen Claude.

Related MCP server: OpenDART MCP Server

Derzeit enthaltene APIs (erster Kernbereich)

Da es zu aufwändig wäre, die gesamte Liste (ca. 40) auf einmal zu implementieren, wurden zunächst die vier Kerninstitutionen, die der Verantwortliche am häufigsten nutzt, vollständig umgesetzt. Die restlichen können nach dem gleichen Muster im Erweiterungsleitfaden nach und nach hinzugefügt werden.

Anleitung zur API‑Schlüsselbeantragung

Auch wenn Sie noch keine Schlüssel haben, startet der Server normal und die Werkzeugliste wird angezeigt. Beim tatsächlichen Aufruf der Werkzeuge wird jedoch eine Meldung zurückgegeben, dass der Schlüssel fehlt. Beantragen Sie daher die benötigten Schlüssel der Reihe nach.

Sobald Sie die Schlüssel haben, kopieren Sie .env.example in .env und füllen Sie die Werte ein.

cp .env.example .env
# .env 파일을 열어 발급받은 키 입력

Schnellstart (Docker)

git clone <이 레포 주소>
cd korea-public-data-mcp
cp .env.example .env   # 키 채워넣기 (없어도 일단 진행 가능)
docker build -t korea-public-data-mcp .

Registrieren Sie den Server in den MCP‑Einstellungen von Claude Desktop / Claude Code (z. B. claude_desktop_config.json) wie folgt.

{
  "mcpServers": {
    "korea-public-data": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--env-file", "/절대경로/korea-public-data-mcp/.env",
        "korea-public-data-mcp"
      ]
    }
  }
}

Nach einem Neustart von Claude erscheinen in der Werkzeugliste die Werkzeuge dart_*, ecos_*, kosis_*, data_go_kr_*. Wenn Sie nun eine Frage wie „Wie hoch war der Umsatz von Samsung Electronics im Jahr 2023?“ stellen, ruft Claude diese Werkzeuge auf und antwortet mit den tatsächlichen Zahlen.

Lokale Entwicklung/Test (ohne Docker)

python -m venv .venv && source .venv/bin/activate
pip install -e .
pip install pytest
pytest -q                      # 키 없이도 통과하는 스모크 테스트
python -m korea_public_data_mcp.server   # stdio로 직접 실행해보기 (Ctrl+C로 종료)

Erweiterungsleitfaden (Neue API hinzufügen)

Die gesamte vom Verantwortlichen übergebene Liste (RISS, KIPRIS, 국가법령정보, 나라장터, 서울 열린데이터광장 usw.) kann nach dem folgenden Muster wiederholt werden. Beispiel: Um eine neue Institution foo hinzuzufügen:

1. In src/korea_public_data_mcp/config.py unter API_KEYS einen Eintrag für foo hinzufügen (env var, Ausgabestelle‑URL)

2. src/korea_public_data_mcp/clients/foo.py erstellen – nur die tatsächliche Endpunkt‑Aufruflogik unter Verwendung von core/http_client.get_json schreiben (Wiederholungen/Geschwindigkeitsbegrenzung werden vom gemeinsamen Client automatisch behandelt)

3. src/korea_public_data_mcp/tools/foo_tools.py erstellen – die Client‑Funktion mit dem @mcp.tool()‑Dekorator umschließen, MissingApiKeyError abfangen und als Hinweismeldung zurückgeben, mit cached_call cachen

4. In src/korea_public_data_mcp/server.py eine Zeile foo_tools.register(mcp) hinzufügen

5. Einträge in .env.example und der README‑Tabelle hinzufügen

Dank dieser Struktur muss bei jeder neuen API die Sperrverhinderungslogik (Geschwindigkeitsbegrenzung/Cache/Batch) nicht neu geschrieben werden.

Nächste Erweiterungskandidaten (basierend auf der Anfragenliste des Verantwortlichen)

• Recht/Verwaltung: 국가법령정보 Open API, 열린국회정보 API

• Beschaffung/Aufträge: 나라장터(g2b), 조달데이터허브, NTIS 국가과학기술정보

• Akademisch: RISS, KISTI, 국립중앙도서관 OpenAPI

• Geistiges Eigentum: KIPRIS Plus (특허·상표)

• Regional: 서울 열린데이터광장, 경기데이터드림

Teilen Sie mir die Priorität oder die nächste hinzuzufügende API mit, dann implementiere ich sie ab diesem Punkt.

Lizenz

Für den internen Gebrauch frei verwendbar und modifizierbar.