Kakao Bot MCP Server

Conecta un agente de IA a una cuenta oficial de Kakao mediante la API de Kakao Developers.

Documentación

Kakao Bot MCP Server

Kakao Bot MCP Server
Ejemplo
Herramientas
- instalación
  - Paso 1. Crear una aplicación de Kakao en developers.kakao.com
  - Paso 2. Configuración del entorno local

Model Context Protocol (MCP) es una implementación de servidor que integra la API de Kakao Developers para conectar un Agente de IA a la Cuenta Oficial de Kakao.

Es un ejemplo de implementación de servidor MCP que integra la API de Kakao Developers a un Agente de IA.

[!NOTE] Este repositorio NO es proporcionado ni mantenido oficialmente por Kakao.
Puede no incluir funcionalidad completa o soporte integral.
En el caso de Kakao, la mayoría de las API gestionan los permisos a nivel de aplicación de negocio que incluye registro de empresa, por lo que
su uso es limitado para individuos.

Documento de referencia: https://developers.kakao.com/docs/latest/ko/kakaotalk-message/rest-api

Ejemplo

Ejecutar la herramienta MCP con claude desktop

Resultado de 'Enviar mensaje a mí mismo'

Herramientas

Todas las herramientas requieren la entrada __email_address__ para identificar las credenciales del usuario.

Kakao TalkMessage API

A partir de la fecha de redacción, solo se admite la API 'Enviar a mí mismo - Plantilla básica'.
Documento de referencia: https://developers.kakao.com/docs/latest/ko/kakaotalk-message/rest-api#default-template-msg-me

send_text_template_to_me
- Descripción: Envía un mensaje de texto de Kakao Talk a mí mismo.
- Entradas:
  - __email_address__ (cadena, obligatorio): La dirección de correo electrónico asociada con la cuenta de Kakao.
  - text (cadena, obligatorio, máximo 200 caracteres): El contenido de texto del mensaje.
  - link (objeto, obligatorio): Un objeto que define el enlace asociado con el texto.
    - web_url (cadena, opcional, formato uri)
    - mobile_web_url (cadena, opcional, formato uri)
  - button_title (cadena, opcional): El título del botón.
send_feed_template_to_me
- Descripción: Envía un mensaje de feed de Kakao Talk a mí mismo.
- Entradas:
  - __email_address__ (cadena, obligatorio)
  - content (objeto, obligatorio): El bloque de contenido principal del mensaje de feed.
    - title (cadena, obligatorio)
    - description (cadena, obligatorio)
    - image_url (cadena, obligatorio, formato uri)
    - image_width (entero, opcional)
    - image_height (entero, opcional)
    - link (objeto, obligatorio) - define el enlace para el contenido
      - web_url (cadena, opcional, formato uri)
      - mobile_web_url (cadena, opcional, formato uri)
      - android_execution_params (cadena, opcional)
      - ios_execution_params (cadena, opcional)
  - item_content (objeto, opcional): Contenido de elemento adicional para el feed. (Consulte la documentación de la API para la estructura anidada)
  - social (objeto, opcional): Información social como me gusta, comentarios, etc. (Consulte la documentación de la API para la estructura anidada)
  - buttons (matriz de objetos, opcional): Botones para incluir con el mensaje. (Cada objeto requiere title y link)
send_list_template_to_me
- Descripción: Envía un mensaje de lista de Kakao Talk a mí mismo.
- Entradas:
  - __email_address__ (cadena, obligatorio)
  - header_title (cadena, obligatorio): El título mostrado en la parte superior de la lista.
  - contents (matriz de objetos, obligatorio): Una lista de elementos de contenido. Cada elemento requiere:
    - title (cadena, obligatorio)
    - description (cadena, obligatorio)
    - image_url (cadena, obligatorio, formato uri)
    - image_width (entero, opcional)
    - image_height (entero, opcional)
    - link (objeto, obligatorio) - define el enlace para el elemento de la lista
      - web_url (cadena, opcional, formato uri)
      - mobile_web_url (cadena, opcional, formato uri)
      - android_execution_params (cadena, opcional)
      - ios_execution_params (cadena, opcional)
  - header_link (objeto, opcional): Un enlace para el área de encabezado. (Consulte la documentación de la API para la estructura anidada)
  - buttons (matriz de objetos, opcional): Botones para incluir con el mensaje. (Cada objeto requiere title y link)
send_location_template_to_me
- Descripción: Envía un mensaje de ubicación de Kakao Talk a mí mismo.
- Entradas:
  - __email_address__ (cadena, obligatorio)
  - content (objeto, obligatorio): El bloque de contenido principal para el mensaje de ubicación.
    - title (cadena, obligatorio)
    - description (cadena, obligatorio)
    - image_url (cadena, obligatorio, formato uri)
    - image_width (entero, opcional)
    - image_height (entero, opcional)
    - link (objeto, obligatorio) - define el enlace para el contenido
      - web_url (cadena, opcional, formato uri)
      - mobile_web_url (cadena, opcional, formato uri)
      - android_execution_params (cadena, opcional)
      - ios_execution_params (cadena, opcional)
  - address (cadena, obligatorio): La dirección de la ubicación.
  - buttons (matriz de objetos, opcional): Botones para incluir con el mensaje. (Cada objeto requiere title y link)
  - address_title (cadena, opcional): Un título para la dirección.
send_calendar_template_to_me
- Descripción: Envía un mensaje de calendario de Kakao Talk a mí mismo.
- Entradas:
  - __email_address__ (cadena, obligatorio)
  - content (objeto, obligatorio): El bloque de contenido principal para el mensaje de calendario.
    - title (cadena, obligatorio)
    - description (cadena, obligatorio)
    - link (objeto, obligatorio) - define el enlace para el contenido
      - web_url (cadena, opcional, formato uri)
      - mobile_web_url (cadena, opcional, formato uri)
      - android_execution_params (cadena, opcional)
      - ios_execution_params (cadena, opcional)
    - image_url (cadena, opcional, formato uri)
  - id_type (cadena, obligatorio, enum: "event"): El tipo de elemento de calendario.
  - id (cadena, obligatorio): El ID del elemento de calendario.
  - buttons (matriz de objetos, opcional): Botones para incluir con el mensaje. (Cada objeto requiere title y link)
send_commerce_template_to_me
- Descripción: Envía un mensaje de comercio de Kakao Talk a mí mismo.
- Entradas:
  - __email_address__ (cadena, obligatorio)
  - content (objeto, obligatorio): El bloque de contenido principal para el mensaje de comercio.
    - title (cadena, obligatorio)
    - image_url (cadena, obligatorio, formato uri)
    - image_width (entero, opcional)
    - image_height (entero, opcional)
    - link (objeto, obligatorio) - define el enlace para el contenido
      - web_url (cadena, opcional, formato uri)
      - mobile_web_url (cadena, opcional, formato uri)
      - android_execution_params (cadena, opcional)
      - ios_execution_params (cadena, opcional)
  - commerce (objeto, obligatorio): Información específica de comercio.
    - regular_price (entero, obligatorio)
    - discount_price (entero, opcional)
    - discount_rate (entero, opcional, 0-100)
  - buttons (matriz de objetos, opcional): Botones para incluir con el mensaje. (Cada objeto requiere title y link)

Kakao TalkCalendar API

Es una herramienta para consultar y gestionar el calendario del usuario a través de la API de Kakao TalkCalendar.
- A partir de la fecha de redacción, solo se admiten las funciones 'Obtener lista de calendarios del usuario, crear / modificar / eliminar subcalendarios'.
- Para la API de TalkCalendar, se debe solicitar permiso de uso a Kakao. Consulte https://developers.kakao.com/docs/latest/ko/talkcalendar/common#policy-request-permission para el método de solicitud.
Documento de referencia: https://developers.kakao.com/docs/latest/ko/talkcalendar/rest-api

get_calendar_list
- Descripción: Recupera la lista de calendarios del usuario.
- Entradas:
  - __email_address__ (cadena, obligatorio): La dirección de correo electrónico asociada con la cuenta de Kakao.
create_sub_calendar
- Descripción: Crea un nuevo subcalendario para el usuario.
- Entradas:
  - __email_address__ (cadena, obligatorio): La dirección de correo electrónico asociada con la cuenta de Kakao.
  - name (cadena, obligatorio): El nombre del subcalendario.
  - color (cadena, opcional): El color predeterminado para los eventos del calendario.
  - reminder (entero, opcional): El tiempo de recordatorio predeterminado para eventos que no son de todo el día, en minutos.
  - reminder_all_day (entero, opcional): El tiempo de recordatorio predeterminado para eventos de todo el día, en minutos.
update_sub_calendar
- Descripción: Actualiza un subcalendario existente.
- Entradas:
  - __email_address__ (cadena, obligatorio): La dirección de correo electrónico asociada con la cuenta de Kakao.
  - calendar_id (cadena, obligatorio): El ID del subcalendario a actualizar.
  - name (cadena, opcional): El nuevo nombre para el subcalendario.
  - color (cadena, opcional): El nuevo color predeterminado para los eventos del calendario.
  - reminder (entero, opcional): El nuevo tiempo de recordatorio predeterminado para eventos que no son de todo el día, en minutos.
  - reminder_all_day (entero, opcional): El nuevo tiempo de recordatorio predeterminado para eventos de todo el día, en minutos.
delete_sub_calendar
- Descripción: Elimina un subcalendario del usuario.
- Entradas:
  - __email_address__ (cadena, obligatorio): La dirección de correo electrónico asociada con la cuenta de Kakao.
  - calendar_id (cadena, obligatorio): El ID del subcalendario a eliminar.

instalación

requisitos: Python 3.13+

Se requiere una cuenta de Kakao

Paso 1. Crear una aplicación de Kakao en developers.kakao.com

Consulte el documento quick start para conocer cómo crear una nueva aplicación de Kakao.

Trabajo adicional para activar la API de mensajes

사이트 등록

En 'Mi aplicación > Configuración de la aplicación > Plataforma', registre http://localhost:8000 como dominio del sitio en Web.

비즈 앱 등록

Registro de la aplicación Biz. Es posible registrar una 'aplicación Biz de desarrollador individual' incluso sin número de negocio.

카카오 로그인 활성화

Activar el inicio de sesión de Kakao.

동의항목 설정

En Configuración del producto > Inicio de sesión de Kakao > Elementos de consentimiento, active 'Apodo', 'Cuenta de Kakao (correo electrónico)', 'Envío de mensajes de KakaoTalk'.
Activar OpenID.
Si se necesita la API de TalkCalendar, se debe solicitar permiso de uso consultando https://developers.kakao.com/docs/latest/ko/talkcalendar/common#policy-request-permission.

Paso 2. Configuración del entorno local

Se debe tener uv instalado localmente.

git clone git@github.com:inspirit941/kakao-bot-mcp-server.git
cd kakao-bot-mcp-server
pip install uv
uv sync

# inspector 실행
npx @modelcontextprotocol/inspector uv --directory .  run mcp-kakao

# MCP server 실행
uv run mcp-kakao

Para que funcione correctamente, se necesitan dos archivos. .accounts.json, .kauth.json Cree los siguientes archivos en la ruta raíz del proyecto.

.accounts.json


{
    "accounts": [
        {
            "email": "your-email@kakao.com",
            "account_type": "personal",
            "extra_info": "Additional info that you want to tell Claude: E.g. 'Contains Family Calendar'"
        }
    ]
}

email: dirección de correo electrónico de la cuenta de Kakao.
account_type: personal fijo.
extra_info: información adicional para pasar al servidor MCP.

.kauth.json

{
  "web": {
    "client_id": "rest-api-key",
    "auth_uri": "https://kauth.kakao.com/oauth/authorize",
    "token_uri": "https://kauth.kakao.com/oauth/token",
    "client_secret": "your_client_secret",
    "redirect_uris": ["http://localhost:8000/code"],
    "revoke_uri": "https://kapi.kakao.com/v2/user/revoke/scopes",
    "token_info_uri": "https://kauth.kakao.com/oauth/tokeninfo"
  }
}

client_id: clave REST_API proporcionada por la aplicación de Kakao.
client_secret: client_secret que se puede obtener de la aplicación de Kakao. Funciona incluso si se introduce una cadena arbitraria.
Los demás campos son fijos.

Configuración de claude desktop

{
  "mcpServers": {
    "mcp-kakao": {
      "command": "uv",
      "args": [
        "--directory",
        "your-project-path/kakao-bot-mcp-server",
        "run",
        "mcp-kakao"
      ]
    }
  }
}

Modo de funcionamiento

Cuando el LLM ejecuta la herramienta MCP:

Comprueba si existe el archivo .oauth2.<카카오메일주소>.json en la ruta raíz del proyecto.
- Si el archivo no existe, muestra la pantalla de inicio de sesión del servidor OAuth2 de Kakao en el navegador web. (https://accounts.kakao.com/login?continue=...)
- Si el archivo existe, comprueba si el token ha expirado. Si ha expirado, se reemite con el token de actualización. Si el token de actualización también ha expirado, la herramienta devuelve una URL donde se puede iniciar sesión.
Si el inicio de sesión es exitoso, guarda la información de access_token con el nombre .oauth2.<카카오메일주소>.json en la ruta raíz del proyecto.

La herramienta MCP utiliza el token de acceso del archivo json.