KakaoTalk Local MCP

Es un puente no oficial y local-first que conecta la aplicación de KakaoTalk para PC con un cliente MCP local. Solo maneja las salas de chat que el usuario haya permitido explícitamente; el envío de mensajes y las respuestas automáticas están desactivados por defecto.

[!WARNING] Este proyecto no está afiliado a Kakao Corp. ni es un producto oficial de Kakao. Las funciones pueden dejar de funcionar según las actualizaciones de KakaoTalk. Antes de usarlo, verifique usted mismo los términos de servicio de KakaoTalk y las leyes aplicables.

Características principales

• Solo accede a las salas de chat registradas en la lista de permitidos.

• Expone al exterior un room_id opaco definido por el usuario en lugar del título real de la sala.

• Al observar por primera vez, guarda el estado actual como línea base para no reproducir conversaciones pasadas como mensajes nuevos.

• Bloquea mensajes duplicados y operaciones repetidas mediante fingerprint y estado de idempotencia.

• El envío de respuestas sigue el orden prepare → 사용자 승인 → commit → readback.

• Los valores predeterminados de send_enabled y auto_reply_enabled son false.

• Opcionalmente, puede seleccionar candidatos de agenda localmente y pasarlos a un agente de gestión de agenda independiente.

• El backend watcher opcional solo procesa un pequeño número de salas elegidas explícitamente y no guarda la clave sin procesar ni la base de datos en texto plano como archivos.

• No llama a modelos de IA en estado inactivo.

Related MCP server: kakaotalk-mcp

Límites de seguridad

Este proyecto no ofrece las siguientes funciones:

• Extracción de contraseñas, sesiones o credenciales de cuentas de KakaoTalk

• Implementación de protocolos de red privados

• Recopilación ilimitada de todas las salas de chat

• Exportación de conversaciones completas

• Almacenamiento de la clave sin procesar de la base de datos o de la base de datos en texto plano

• Envío masivo de mensajes

• Respuestas automáticas sin aprobación

No exponga el servidor MCP local directamente a Internet o a redes públicas. Se recomienda no subir la configuración real, la base de datos de estado, los registros y las capturas de chat a un repositorio Git ni a una carpeta de sincronización en la nube.

Requisitos del entorno

• Windows 10 o Windows 11

• Aplicación de KakaoTalk para PC con sesión iniciada

• Python 3.11 o superior

• PowerShell

• Un cliente MCP que pueda ejecutar un servidor MCP stdio

Instalación

Descargue el repositorio en PowerShell y ejecute el script de instalación.

git clone https://github.com/Bum-Boo/kakaotalk-local-mcp.git
cd kakaotalk-local-mcp
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-windows.ps1

El script de instalación crea un .venv exclusivo para el proyecto y solo copia una configración de ejemplo segura si no existe config.json.

Configuración básica

config.json no está incluido en el repositorio públic. Al principio, comience con el envío y la automatización de agenda desactivados.

{
  "adapter": "win32",
  "send_enabled": false,
  "auto_reply_enabled": false,
  "schedule_automation_enabled": false,
  "backend_collector": null,
  "rooms": []
}

Registro de salas de chat

Abra solo una sala de chat de destino en una ventana separada y ejecte el siguiente comando para registrarla sin mostar el título de la sala en la consola.

.\.venv\Scripts\hermes-kakao-mcp.exe --config .\config.json adopt-open-room --room-id self-test

Si no hay exactamente una sala de chat abierta, no se modifica la configración. room_id es un alias local para usar en MCP y no tiene que coincidir con el título real de la sala de chat.

Después de aplicar la configuración, compruébelo con el siguiente comando.

.\.venv\Scripts\hermes-kakao-mcp.exe --config .\config.json validate-config
.\scripts\doctor.cmd

Conexión del cliente MCP

En la configuración del servidor stdio de su cliente MCP, añada el siguiente ejecutable. Debe reemplazarlo con la ruta real del repositorio.

{
  "mcpServers": {
    "kakaotalk-local": {
      "command": "C:\\Windows\\System32\\cmd.exe",
      "args": [
        "/d",
        "/s",
        "/c",
        "C:\\path\\to\\kakaotalk-local-mcp\\scripts\\run-mcp.cmd"
      ]
    }
  }
}

Después de conectarse, llame primero solo a kakao_health para comprobar el estado del puente local y que el envío esté desactivado.

Herramientas proporcionadas

Envío de mensajes

Incluso si necesita realizar un envío real, siga el siguiente orden:

1. Compruebe el fingerprint más reciente con kakao_read_room.

2. Muestre al usuario el borrador que se va a enviar.

3. Prepare la operación de un solo uso con kakao_prepare_reply.

4. El usuario aprueba explícitamente en el turno actual.

5. Llame a kakao_commit_reply una sola vez.

6. Si aparecen mensajes más recientes o el resultado del readback no es claro, no reintente automáticamente.

Si send_enabled en la configración es false, no se envía nada en la fase de commit.

Watcher opcional

El watcher de UI normal se puede ejectar de la siguiente manera:

.\.venv\Scripts\hermes-kakao-watch.exe --once
.\.venv\Scripts\hermes-kakao-watch.exe

Use el backend watcher opcional solo si ha configurado los IDs de sala aproados por separado y la versión actual de KakaoTalk.

{
  "backend_collector": {
    "enabled": true,
    "mode": "ram_only_v2",
    "room_ids": ["approved-room-one"],
    "max_batch_rows": 200,
    "bootstrap_retry_seconds": 30,
    "expected_client_version": "현재 검증한 버전"
  }
}

Si la versión de KakaoTalk difiere del valor configurado, el backend watcher se detiene antes de acceder a los datos.

Desarrolo y verificación

uv sync --extra dev
uv run ruff check .
uv run pytest
uv run python tests\smoke_mcp.py

GitHub Actions también verifica las combinaciones de Windows y Ubuntu con Python 3.11 y 3.12.

Solicitud de atribución al creador

Si publica artículos, vídos, demos, investigaciones o proyectos derivados que usen este proyecto, le agradeceríamos que mencione al creador y al repositorio como se muestra a continuación:

Hecho con KakaoTalk Local MCP por @Bum-Boo

Asegúrese de mantener el aviso de copyright y licencia que exige la licencia MIT. La mención pública mediante el texto anterior no pretende añadir condiciones legales, sino pedir que se pueda encontrar a la persona que hizo el proyecto y el repositorio original.

Proyectos que inspiraron

Nos inspiramos en las ideas y el trabajo previo de los siguientes proyectos de código abierto. Agradecemos a sus creadores por publicar su excelente trabajo.

• kronenz/kakaotalk-mcp — enfoque para la exploración de ventanas Win32 y la conexión MCP

• johklo/moltbot — línea base, fingerprint de mensajes y revalidación antes del envío

• channprj/kmsg — alias local, gestión de estado limitada y diseño fail-closed

• is-theo/kakao-cli-win — punto de partida para la investigación de la estructura SQLCipher v2 en Windows

Las revisiones consultadas y la información de licencias están documentadas en THIRD_PARTY_NOTICES.md. Esto no significa que se incluyan directamente los códigos de los proyectos mencionados ni que reciban soporte oficial.

Privacidad, seguridad y licencia

• Límites del tratamiento de datos personales: PRIVACY.md

• Reporte de vulnerabilidades y modelo de amenazas: SECURITY.md

• Avisos de terceros: THIRD_PARTY_NOTICES.md

• Licencia: MIT