korea-public-data-mcp

Un servidor MCP que permite a Claude invocar directamente datos públicos de Corea (OpenDART de la Comisión de Servicios Financieros, ECOS del Banco de Corea, KOSIS de la Oficina de Estadística, Portal de Datos Públicos) y responder preguntas sobre finanzas, economía y estadísticas basándose en respuestas reales de la API, no en suposiciones.

De la misma manera que los MCP que utilizan datos de divulgación electrónica de DART para responder preguntas sobre estados financieros, preguntas como "¿Cuánto fueron las ventas del año pasado de esta empresa?", "¿Cuál es la tendencia reciente de la tasa de interés de referencia?" o "¿Cuál es la tasa de desempleo de nuestro país?" harán que Claude invoque las herramientas de este servidor y responda basándose en las cifras más recientes.

El nombre es temporal como korea-public-data-mcp. Al subirlo a GitHub, puede cambiarlo libremente al nombre que desee sin que afecte el funcionamiento del código.

Por qué se hizo así (Principios de diseño)

Se diseñó respetando las tres restricciones solicitadas por la persona responsable.

1. Sin costos de LLM/externos — Este servidor solo "obtiene" datos. No invoca ningún LLM internamente ni utiliza APIs de pago. El razonamiento/resumen real lo realiza Claude que invoca este MCP, por lo que el costo operativo del servidor es prácticamente cero (excluyendo electricidad/recursos del servidor).

2. Prevención de bloqueo de API (baneo de IP) — Las APIs públicas gubernamentales pueden bloquear temporalmente si se superan los límites de llamadas por segundo/día. Por lo tanto:

   • Se aplica un límite de llamadas por segundo (token bucket) al frente de todas las llamadas API para ralentizar la velocidad automáticamente.

   • Las mismas preguntas repetidas se reutilizan mediante caché en memoria, y los archivos estáticos grandes como la lista de empresas de DART se almacenan en caché de disco (7 días por defecto) para evitar descargas repetidas.

   • En lugar de llamar individualmente a cada cuenta/período, se obtienen por tabla y rango de períodos de una sola vez (por ejemplo, los estados financieros obtienen todas las cuentas en una sola llamada por empresa, y las estadísticas consultan el período de inicio a fin de una sola vez).

   • Para APIs que admiten procesamiento por lotes, como la consulta de estado de registro de negocios, se agrupan hasta 100 casos en una sola llamada.

   • Ante respuestas 429/5xx, se reintenta con retroceso exponencial hasta un máximo de 3 veces.

3. Cada uno ejecuta con Docker — Sin levantar un servidor separado, cada miembro del equipo levanta localmente con docker build + docker run y lo conecta a su propio Claude.

APIs incluidas actualmente (Alcance principal de la 1.ª fase)

Implementar las más de 40 solicitudes de una sola vez sería difícil de mantener, por lo que primero se implementaron con integridad las 4 instituciones principales que la persona responsable consulta con más frecuencia. El resto se puede agregar siguiendo el mismo patrón según la guía de extensión.

Guía de obtención de clave API

Incluso si aún no ha obtenido una clave, el servidor se iniciará correctamente y se mostrará la lista de herramientas. Sin embargo, al invocar las herramientas, se devolverá un mensaje indicando que falta la clave, así que solicítelas en orden según sea necesario.

Una vez que tenga las claves, copie .env.example a .env y complételo.

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

Inicio rápido (Docker)

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

Regístrelo en la configuración MCP de Claude Desktop / Claude Code (claude_desktop_config.json, etc.) como se muestra a continuación.

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

Al reiniciar Claude, aparecerán las herramientas dart_*, ecos_*, kosis_*, data_go_kr_* en la lista de herramientas. Ahora, si hace preguntas como "Dime las ventas de Samsung Electronics en 2023", Claude invocará estas herramientas y responderá con cifras reales.

Desarrollo/pruebas locales (sin 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로 종료)

Guía de extensión (Agregar nueva API)

Para la lista completa proporcionada por la persona responsable (RISS, KIPRIS, Información Legal Nacional,나라장터, Plaza de Datos Abiertos de Seúl, etc.), simplemente repita el siguiente patrón. Por ejemplo, para agregar una nueva institución foo:

1. Agregar el elemento foo en API_KEYS de src/korea_public_data_mcp/config.py (variable de entorno, URL de emisión)

2. Crear src/korea_public_data_mcp/clients/foo.py — usar core/http_client.get_json para escribir solo la lógica de llamada al endpoint real (el reintento/límite de velocidad lo maneja automáticamente el cliente común)

3. Crear src/korea_public_data_mcp/tools/foo_tools.py — envolver la función del cliente con el decorador @mcp.tool(), capturar MissingApiKeyError para devolver un mensaje informativo, y usar cached_call para almacenar en caché

4. Agregar una línea foo_tools.register(mcp) en src/korea_public_data_mcp/server.py

5. Agregar elementos en .env.example y la tabla del README

Gracias a esta estructura, al agregar una nueva API no es necesario volver a escribir la lógica de prevención de bloqueo (límite de velocidad/caché/lote) cada vez.

Próximos candidatos para extensión (Basado en la lista de solicitudes de la persona responsable)

• Leyes/Administración: Open API de Información Legal Nacional, Open API de Información del Parlamento Abierto

• Contratación/Negocios: 나라장터(g2b), Centro de Datos de Contratación, NTIS Información Nacional de Ciencia y Tecnología

• Académico: RISS, KISTI, OpenAPI de la Biblioteca Nacional de Corea

• Propiedad Intelectual: KIPRIS Plus (patentes/marcas)

• Regional: Plaza de Datos Abiertos de Seúl, Gyeonggi Data Dream

Si me indica la prioridad o la próxima API a agregar, la implementaré a partir de ese elemento.

Licencia

Siéntase libre de usar/modificar para uso interno.