Servidor MCP de Kakao Bot

Servidor MCP de Kakao Bot
예시
Herramientas
- instalación
  - Paso 1.developers.kakao.com 에서 카카오 애플리케이션 생성
  - Paso 2. 로컬환경 설정

Implementación del servidor de Protocolo de contexto de modelo (MCP) que integra la API de desarrolladores de Kakao para conectar un agente de IA a la cuenta oficial de Kakao.

MCP Server 구현체로, 카카오 Developers API를 AI Agent에 통합하는 예시입니다.

[!NOTE] Kakao NO proporciona ni mantiene oficialmente este repositorio. Es posible que no incluya funcionalidad completa o soporte integral. 카카오의 경우 대부분의 API가 사업자등록이 포함된 비즈니스 애플리케이션 단위로 권한을 관리하고 있으므로, 개인이 사용하기엔 제한적입니다.

Texto: https://developers.kakao.com/docs/latest/ko/kakaotalk-message/rest-api

예시

Claude Desktop: herramienta MCP

'나에게 메시지 전달' 결과

Herramientas

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

작성시점 기준, '나에게 보내기 - 기본 템플릿' API만 지원됩니다.
Texto: https://developers.kakao.com/docs/latest/ko/kakaotalk-message/rest-api#default-template-msg-me

envíame una plantilla de texto
- Descripción: Me envía un mensaje de texto de Kakao Talk.
- Entradas:
  - __email_address__ (cadena, obligatoria): 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.
Envíame una plantilla de feed
- Descripción: Me envía un mensaje de feed de Kakao Talk.
- Entradas:
  - __email_address__ (cadena, obligatoria)
  - content (objeto, obligatorio): el bloque de contenido principal del mensaje de feed.
    - title (cadena, obligatorio)
    - description (cadena, obligatoria)
    - 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 adicional del elemento para el feed. (Consulte la documentación de la API para ver la estructura anidada).
  - social (objeto, opcional): información social como "me gusta", comentarios, etc. (Consulte la documentación de la API para ver la estructura anidada)
  - buttons (matriz de objetos, opcional): Botones para incluir con el mensaje. (Cada objeto requiere title y link ).
Envíame una plantilla de lista
- Descripción: Me envía un mensaje de la lista de Kakao Talk.
- Entradas:
  - __email_address__ (cadena, obligatoria)
  - header_title (cadena, obligatoria): el título que se muestra 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, obligatoria)
    - 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 ver la estructura anidada).
  - buttons (matriz de objetos, opcional): Botones para incluir con el mensaje. (Cada objeto requiere title y link ).
Envíame una plantilla de ubicación
- Descripción: Me envía un mensaje de ubicación de Kakao Talk.
- Entradas:
  - __email_address__ (cadena, obligatoria)
  - content (objeto, obligatorio): el bloque de contenido principal para el mensaje de ubicación.
    - title (cadena, obligatorio)
    - description (cadena, obligatoria)
    - 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, obligatoria): 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.
envíame una plantilla de calendario
- Descripción: Me envía un mensaje de calendario de Kakao Talk.
- Entradas:
  - __email_address__ (cadena, obligatoria)
  - content (objeto, obligatorio): el bloque de contenido principal para el mensaje del calendario.
    - title (cadena, obligatorio)
    - description (cadena, obligatoria)
    - 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, enumeración: "evento"): el tipo de elemento del calendario.
  - id (cadena, obligatoria): el ID del elemento del calendario.
  - buttons (matriz de objetos, opcional): Botones para incluir con el mensaje. (Cada objeto requiere title y link ).
envíame una plantilla de comercio
- Descripción: Me envía un mensaje comercial de Kakao Talk.
- Entradas:
  - __email_address__ (cadena, obligatoria)
  - content (objeto, obligatorio): el bloque de contenido principal para el mensaje comercial.
    - 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 del 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 ).

instalación

Requisitos: Python 3.13+

카카오 계정 필요

Paso 1.developers.kakao.com 에서 카카오 애플리케이션 생성

카카오 신규 애플리케이션 생성 방법은 inicio rápido 문서를 참고합니다.

"내 애플리케이션 > 앱 설정 > 플랫폼" 의 Web에서 사이트 도메인으로 http://localhost:8000 등록

비즈 앱 등록. 사업자번호가 없어도 "개인 개발자 비즈 앱" 등록이 가능하다.

카카오 로그인을 활성화한다.

제품 설정 > 카카오 로그인 > 동의항목에서 '닉네임', '카카오계정(이메일)', '카카오톡 메시지 전송' 을 활성화한다.
OpenID 활성화한다.

Paso 2. 로컬환경 설정

로컬에 uv가 설치되어 있어야 한다.

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

정상적으로 동작하려면 두 개의 파일이 필요하다. .accounts.json , .kauth.json 프로젝트 root 경로에 아래 파일을 생성한다.

.cuentas.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'"
        }
    ]
}

correo electrónico: 카카오 계정 이메일주소.
tipo_cuenta: cuenta personal.
extra_info: 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
client_secret: Establece la configuración de client_secret. 임의의 문자열을 넣어도 동작함
나머지 필드는 고정.

claude escritorio 설정

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

동작 방식

LLM이 MCP Tool을 실행하면

프로젝트 raíz 경로에 .oauth2.<카카오메일주소>.json 파일이 있는지 확인한다.
- Establece una conexión con OAuth2 y una conexión con OAuth2. (https: //accounts.kakao.com/login ?continue=...)
- 파일이 있을 경우, 토큰이 만료되지 않았는지 확인한다. 만료되었다면, actualizar token으로 재발급받는다. actualizar token도 만료되었을 경우, herramienta에서 로그인할 수 있는 url 주소를 리턴한다.
Utilice la raíz .oauth2.<카카오메일주소>.json y acceda al token de acceso. 저시한다.

Herramienta MCP: json y token de acceso.

Kakao Bot MCP Server

Integrations