korea-public-data-mcp

Ein MCP-Server, der es Claude ermöglicht, südkoreanische öffentliche Daten (Finanzaufsichtsbehörde OpenDART, Bank of Korea ECOS, Statistikamt KOSIS, Portal für öffentliche Daten) direkt abzurufen und finanzielle, wirtschaftliche und statistische Werte nicht durch Schätzung, sondern basierend auf tatsächlichen API-Antworten zu beantworten.

Analog zu MCPs, die DART-Electronic-Disclosure-Daten für Fragen zu Jahresabschlüssen nutzen, kann Claude mit diesem Server auf Fragen wie „Wie hoch war der Umsatz dieses Unternehmens im letzten Jahr?“, „Wie ist der aktuelle Leitzinstrend?“ oder „Wie hoch ist die Arbeitslosenquote in Südkorea?“ antworten, indem es die Werkzeuge dieses Servers aufruft und die Antworten auf aktuelle Daten stützt.

Der Name ist vorläufig als korea-public-data-mcp gewählt. Wenn Sie es auf GitHub hochladen, können Sie den Namen frei ändern, ohne dass dies Auswirkungen auf die Code-Funktionalität hat.

Warum wurde es so entwickelt? (Entwurfsprinzipien)

Der Server wurde unter Einhaltung der drei von der verantwortlichen Person 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 erfolgt durch Claude, das diesen MCP aufruft. Daher sind die Betriebskosten des Servers praktisch null (ausgenommen Strom-/Serverressourcen).

2. Verhinderung von API-Sperren (IP-Bann) – Öffentliche APIs der Regierung können bei Überschreitung der Aufruflimits pro Sekunde/Tag vorübergehend gesperrt werden. Daher:

   • Allen API-Aufrufen ist ein Aufruflimit pro Sekunde (Token-Bucket) vorgeschaltet, um die Geschwindigkeit selbst zu drosseln.

   • Wiederholte identische Anfragen werden über einen Memory-Cache wiederverwendet, und große statische Dateien wie die DART-Unternehmensliste werden durch einen Disk-Cache (Standard 7 Tage) vor erneuten Downloads geschützt.

   • Konten und Zeiträume werden nicht einzeln aufgerufen, sondern tabellen- und zeitraumweise auf einmal abgerufen (z. B. werden für einen Jahresabschluss alle Konten eines Unternehmens mit einem einzigen Aufruf abgerufen, Statistiken werden für einen gesamten Start- bis Endzeitraum auf einmal abgefragt).

   • Bei APIs, die Batch-Verarbeitung unterstützen, wie der Abfrage des Geschäftsstatus, werden maximal 100 Fälle in einem einzigen Aufruf gebündelt.

   • Bei 429/5xx-Antworten wird mit exponentiellem Backoff maximal 3 Mal wiederholt.

3. Jeder mit Docker – Es wird kein separater Server betrieben. Jedes Teammitglied führt lokal docker build + docker run aus und verbindet es mit seiner eigenen Claude-Instanz.

Derzeit enthaltene APIs (Primärer Kernbereich)

Da die Implementierung aller etwa 40 angeforderten APIs auf einmal den Wartungsaufwand erhöhen würde, wurden zunächst die vier Kerninstitutionen, die von der verantwortlichen Person am häufigsten genutzt werden, vollständig implementiert. Die restlichen können nach dem Erweiterungsleitfaden im gleichen Muster hinzugefügt werden.

Anleitung zur API-Schlüsselbeantragung

Auch wenn Sie noch keinen Schlüssel haben, startet der Server normal und die Werkzeugliste wird angezeigt. Wenn Sie jedoch ein Werkzeug tatsächlich aufrufen, wird eine Meldung zurückgegeben, dass der jeweilige Schlüssel fehlt. Beantragen Sie die Schlüssel daher nach Bedarf in der empfohlenen Reihenfolge.

Nach Erhalt der Schlüssel kopieren Sie .env.example in .env und füllen 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 es in der MCP-Konfiguration (z. B. claude_desktop_config.json) von Claude Desktop / Claude Code wie unten gezeigt.

{
  "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 die Werkzeuge dart_*, ecos_*, kosis_*, data_go_kr_* in der Werkzeugliste. Wenn Sie nun Fragen wie „Wie hoch war der Umsatz von Samsung Electronics im Jahr 2023?“ stellen, ruft Claude diese Werkzeuge auf und antwortet mit den tatsächlichen Werten.

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)

Für die vollständige Liste (RISS, KIPRIS, Nationale Rechtsinformationsdaten, G2B, Seoul Open Data Plaza usw.), die von der verantwortlichen Person bereitgestellt wurde, kann das folgende Muster wiederholt werden. Um beispielsweise eine neue Institution foo hinzuzufügen:

1. Fügen Sie in src/korea_public_data_mcp/config.py zum Dictionary API_KEYS den Eintrag foo hinzu (Env-Variable, Ausstellungs-URL)

2. Erstellen Sie src/korea_public_data_mcp/clients/foo.py – Verwenden Sie core/http_client.get_json, um nur die Logik für den tatsächlichen Endpunktaufruf zu schreiben (Wiederholungs-/Geschwindigkeitsbegrenzung wird automatisch vom gemeinsamen Client behandelt)

3. Erstellen Sie src/korea_public_data_mcp/tools/foo_tools.py – Umhüllen Sie die Client-Funktion mit dem Dekorator @mcp.tool(), fangen Sie MissingApiKeyError ab, um eine Informationsmeldung zurückzugeben, und nutzen Sie cached_call für Caching

4. Fügen Sie in src/korea_public_data_mcp/server.py die Zeile foo_tools.register(mcp) hinzu

5. Aktualisieren Sie .env.example und die Tabelle in der README

Dank dieser Struktur muss die Logik zur Sperrverhinderung (Geschwindigkeitsbegrenzung/Cache/Batch) bei jedem Hinzufügen einer neuen API nicht neu geschrieben werden.

Nächste Erweiterungskandidaten (Basierend auf der Anfragenliste der verantwortlichen Person)

• Recht/Verwaltung: Nationale Rechtsinformationsdaten Open API, Offene Parlamentsdaten API

• Beschaffung/Geschäft: G2B, Beschaffungsdaten-Hub, NTIS Nationale Wissenschafts- und Technologieinformation

• Akademisch: RISS, KISTI, OpenAPI der Nationalbibliothek

• Geistiges Eigentum: KIPRIS Plus (Patente, Marken)

• Regional: Seoul Open Data Plaza, Gyeonggi Data Dream

Wenn Sie mir mitteilen, welche APIs als nächstes Priorität haben oder hinzugefügt werden sollen, implementiere ich diese als nächstes.

Lizenz

Zur freien Verwendung und Modifikation für den internen Gebrauch.