korea-public-data-mcp

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

Al igual que otros MCP que utilizan datos de divulgación electrónica DART para responder preguntas sobre estados financieros, este servidor permite que Claude responda a 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 base?" o "¿Cuál es la tasa de desempleo en nuestro país?" invocando las herramientas de este servidor y fundamentando las respuestas en los datos más recientes.

El nombre es provisional: korea-public-data-mcp. Si lo subes a GitHub, puedes cambiarlo libremente al nombre que desees sin que afecte el funcionamiento del código.

Por qué se diseñó así (principios de diseño)

Se diseñó respetando 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. La inferencia/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 a veces bloquean temporalmente si se superan los límites de llamadas por segundo/día. Por ello:

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

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

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

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

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

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.

Related MCP server: OpenDART MCP Server

APIs incluidas actualmente (alcance principal de la primera fase)

Implementar las 40+ solicitudes completas de una sola vez sería difícil de mantener, por lo que primero se implementaron con alta calidad 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 tienes una clave, el servidor se iniciará correctamente y se mostrará la lista de herramientas. Sin embargo, al invocar una herramienta, se devolverá un mensaje indicando que falta la clave, por lo que puedes solicitar las que necesites en orden.

Una vez que recibas las claves, copia .env.example a .env y complétalas.

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ístralo en la configuración MCP de Claude Desktop / Claude Code (como claude_desktop_config.json) de la siguiente manera.

{
  "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 haces preguntas como "Dime las ventas de Samsung Electronics en 2023", Claude invocará estas herramientas y responderá con datos reales.

Desarrollo/pruebas local (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 agregar las instituciones de la lista completa proporcionada por la persona responsable (RISS, KIPRIS, Sistema Nacional de Información Legal,나라장터, Seoul Open Data Plaza, etc.), simplemente repite el siguiente patrón. Por ejemplo, para agregar una nueva institución foo:

1. Agrega la entrada foo en API_KEYS en src/korea_public_data_mcp/config.py (variable de entorno, URL de emisión)

2. Crea src/korea_public_data_mcp/clients/foo.py — usa core/http_client.get_json para escribir solo la lógica de llamada al endpoint real (los reintentos/límites de velocidad los maneja automáticamente el cliente compartido)

3. Crea src/korea_public_data_mcp/tools/foo_tools.py — envuelve la función del cliente con el decorador @mcp.tool(), captura MissingApiKeyError para devolver un mensaje informativo, y usa cached_call para el almacenamiento en caché

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

5. Agrega las entradas en .env.example y en la tabla del README

Gracias a esta estructura, no es necesario volver a escribir la lógica de prevención de bloqueos (límite de velocidad/caché/procesamiento por lotes) cada vez que se agrega una nueva API.

Próximos candidatos para extensión (según la lista de solicitudes de la persona responsable)

• Legal/Administrativo: Open API del Sistema Nacional de Información Legal, API de Información de la Asamblea Nacional Abierta

• 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: Seoul Open Data Plaza, Gyeonggi Data Dream

Indíqueme la prioridad o la próxima API que desee agregar, y la implementaré a partir de ese punto.

Licencia

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