Kakao Bot MCP Server

Conecta um agente de IA a uma Conta Oficial do Kakao usando a API de Desenvolvedores do Kakao.

GitHub
17
Experimente este MCPPatrocinado

Documentação

Kakao Bot MCP Server

Implementação de servidor Model Context Protocol (MCP) que integra a API Kakao Developers para conectar um Agente de IA à Conta Oficial do Kakao.

Exemplo de implementação de servidor MCP que integra a API Kakao Developers a um Agente de IA.


[!NOTE] Este repositório NÃO é fornecido ou mantido oficialmente pela Kakao.
Pode não incluir funcionalidade completa ou suporte abrangente.
Como a Kakao gerencia permissões principalmente por aplicativos de negócios com registro de empresa,
seu uso é limitado para indivíduos.


Documentação de referência: https://developers.kakao.com/docs/latest/ko/kakaotalk-message/rest-api

예시

스크린샷_2025-05-03_오후_2.36.09

Execução da ferramenta MCP com o claude desktop

스크린샷_2025-05-03_오후_2.37.25

Resultado de 'enviar mensagem para mim'

Tools

Todas as ferramentas exigem a entrada __email_address__ para identificar as credenciais do usuário.

Kakao TalkMessage API

  1. send_text_template_to_me

    • Descrição: Envia uma mensagem de texto do Kakao Talk para mim.
    • Entradas:
      • __email_address__ (string, obrigatório): O endereço de e-mail associado à conta Kakao.
      • text (string, obrigatório, máximo 200 caracteres): O conteúdo de texto da mensagem.
      • link (objeto, obrigatório): Um objeto que define o link associado ao texto.
        • web_url (string, opcional, formato uri)
        • mobile_web_url (string, opcional, formato uri)
      • button_title (string, opcional): O título do botão.

  2. send_feed_template_to_me

    • Descrição: Envia uma mensagem de feed do Kakao Talk para mim.
    • Entradas:
      • __email_address__ (string, obrigatório)
      • content (objeto, obrigatório): O bloco de conteúdo principal da mensagem de feed.
        • title (string, obrigatório)
        • description (string, obrigatório)
        • image_url (string, obrigatório, formato uri)
        • image_width (inteiro, opcional)
        • image_height (inteiro, opcional)
        • link (objeto, obrigatório) - define o link para o conteúdo
          • web_url (string, opcional, formato uri)
          • mobile_web_url (string, opcional, formato uri)
          • android_execution_params (string, opcional)
          • ios_execution_params (string, opcional)
      • item_content (objeto, opcional): Conteúdo adicional de item para o feed. (Consulte a documentação da API para estrutura aninhada)
      • social (objeto, opcional): Informações sociais como curtidas, comentários, etc. (Consulte a documentação da API para estrutura aninhada)
      • buttons (matriz de objetos, opcional): Botões a incluir com a mensagem. (Cada objeto requer title e link)

  3. send_list_template_to_me

    • Descrição: Envia uma mensagem de lista do Kakao Talk para mim.
    • Entradas:
      • __email_address__ (string, obrigatório)
      • header_title (string, obrigatório): O título exibido no topo da lista.
      • contents (matriz de objetos, obrigatório): Uma lista de itens de conteúdo. Cada item requer:
        • title (string, obrigatório)
        • description (string, obrigatório)
        • image_url (string, obrigatório, formato uri)
        • image_width (inteiro, opcional)
        • image_height (inteiro, opcional)
        • link (objeto, obrigatório) - define o link para o item da lista
          • web_url (string, opcional, formato uri)
          • mobile_web_url (string, opcional, formato uri)
          • android_execution_params (string, opcional)
          • ios_execution_params (string, opcional)
      • header_link (objeto, opcional): Um link para a área do cabeçalho. (Consulte a documentação da API para estrutura aninhada)
      • buttons (matriz de objetos, opcional): Botões a incluir com a mensagem. (Cada objeto requer title e link)

  4. send_location_template_to_me

    • Descrição: Envia uma mensagem de localização do Kakao Talk para mim.
    • Entradas:
      • __email_address__ (string, obrigatório)
      • content (objeto, obrigatório): O bloco de conteúdo principal para a mensagem de localização.
        • title (string, obrigatório)
        • description (string, obrigatório)
        • image_url (string, obrigatório, formato uri)
        • image_width (inteiro, opcional)
        • image_height (inteiro, opcional)
        • link (objeto, obrigatório) - define o link para o conteúdo
          • web_url (string, opcional, formato uri)
          • mobile_web_url (string, opcional, formato uri)
          • android_execution_params (string, opcional)
          • ios_execution_params (string, opcional)
      • address (string, obrigatório): O endereço da localização.
      • buttons (matriz de objetos, opcional): Botões a incluir com a mensagem. (Cada objeto requer title e link)
      • address_title (string, opcional): Um título para o endereço.

  5. send_calendar_template_to_me

    • Descrição: Envia uma mensagem de calendário do Kakao Talk para mim.
    • Entradas:
      • __email_address__ (string, obrigatório)
      • content (objeto, obrigatório): O bloco de conteúdo principal para a mensagem de calendário.
        • title (string, obrigatório)
        • description (string, obrigatório)
        • link (objeto, obrigatório) - define o link para o conteúdo
          • web_url (string, opcional, formato uri)
          • mobile_web_url (string, opcional, formato uri)
          • android_execution_params (string, opcional)
          • ios_execution_params (string, opcional)
        • image_url (string, opcional, formato uri)
      • id_type (string, obrigatório, enum: "event"): O tipo de item de calendário.
      • id (string, obrigatório): O ID do item de calendário.
      • buttons (matriz de objetos, opcional): Botões a incluir com a mensagem. (Cada objeto requer title e link)

  6. send_commerce_template_to_me

    • Descrição: Envia uma mensagem de comércio do Kakao Talk para mim.
    • Entradas:
      • __email_address__ (string, obrigatório)
      • content (objeto, obrigatório): O bloco de conteúdo principal para a mensagem de comércio.
        • title (string, obrigatório)
        • image_url (string, obrigatório, formato uri)
        • image_width (inteiro, opcional)
        • image_height (inteiro, opcional)
        • link (objeto, obrigatório) - define o link para o conteúdo
          • web_url (string, opcional, formato uri)
          • mobile_web_url (string, opcional, formato uri)
          • android_execution_params (string, opcional)
          • ios_execution_params (string, opcional)
      • commerce (objeto, obrigatório): Informações específicas de comércio.
        • regular_price (inteiro, obrigatório)
        • discount_price (inteiro, opcional)
        • discount_rate (inteiro, opcional, 0-100)
      • buttons (matriz de objetos, opcional): Botões a incluir com a mensagem. (Cada objeto requer title e link)

Kakao TalkCalendar API

  1. get_calendar_list

    • Descrição: Recupera a lista de calendários do usuário.
    • Entradas:
      • __email_address__ (string, obrigatório): O endereço de e-mail associado à conta Kakao.

  2. create_sub_calendar

    • Descrição: Cria um novo subcalendário para o usuário.
    • Entradas:
      • __email_address__ (string, obrigatório): O endereço de e-mail associado à conta Kakao.
      • name (string, obrigatório): O nome do subcalendário.
      • color (string, opcional): A cor padrão para eventos no calendário.
      • reminder (inteiro, opcional): O horário de lembrete padrão para eventos que não são de dia inteiro, em minutos.
      • reminder_all_day (inteiro, opcional): O horário de lembrete padrão para eventos de dia inteiro, em minutos.

  3. update_sub_calendar

    • Descrição: Atualiza um subcalendário existente.
    • Entradas:
      • __email_address__ (string, obrigatório): O endereço de e-mail associado à conta Kakao.
      • calendar_id (string, obrigatório): O ID do subcalendário a ser atualizado.
      • name (string, opcional): O novo nome para o subcalendário.
      • color (string, opcional): A nova cor padrão para eventos no calendário.
      • reminder (inteiro, opcional): O novo horário de lembrete padrão para eventos que não são de dia inteiro, em minutos.
      • reminder_all_day (inteiro, opcional): O novo horário de lembrete padrão para eventos de dia inteiro, em minutos.

  4. delete_sub_calendar

    • Descrição: Exclui um subcalendário do usuário.
    • Entradas:
      • __email_address__ (string, obrigatório): O endereço de e-mail associado à conta Kakao.
      • calendar_id (string, obrigatório): O ID do subcalendário a ser excluído.

installation

Requisitos: Python 3.13+

Conta Kakao necessária

Step 1. Criação do aplicativo Kakao em developers.kakao.com

Consulte o documento quick start para o método de criação de um novo aplicativo Kakao.

Trabalho adicional para ativar a API de mensagens

사이트 등록

Em "Meus aplicativos > Configurações do aplicativo > Plataforma", registre http://localhost:8000 como domínio do site na seção Web.


비즈 앱 등록

Registro do aplicativo Biz. Mesmo sem número de registro de empresa, é possível registrar um "aplicativo Biz de desenvolvedor individual".


카카오 로그인 활성화

Ative o login Kakao.


동의항목 설정

Step 2. Configuração do ambiente local

O uv deve estar 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 funcionar corretamente, dois arquivos são necessários. .accounts.json, .kauth.json Crie os arquivos abaixo no caminho raiz do projeto.

.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: Endereço de e-mail da conta Kakao.
  • account_type: Fixo como personal.
  • extra_info: Informações adicionais a serem transmitidas ao 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: Chave REST_API fornecida pelo aplicativo Kakao
  • client_secret: client_secret que pode ser emitido pelo aplicativo Kakao. Funciona mesmo com uma string arbitrária
  • Os demais campos são fixos.

Configuração do claude desktop

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

Método de operação


Quando o LLM executa a ferramenta MCP

  • Verifica se o arquivo .oauth2.<카카오메일주소>.json existe no caminho raiz do projeto.
    • Se o arquivo não existir, exibe a tela de login do servidor OAuth2 da Kakao no navegador da web. (https://accounts.kakao.com/login?continue=...)
    • Se o arquivo existir, verifica se o token não expirou. Se expirou, reemite com o refresh token. Se o refresh token também expirou, retorna o endereço URL onde o usuário pode fazer login na ferramenta.
  • Se o login for bem-sucedido, salva as informações de access_token no caminho raiz do projeto com o nome .oauth2.<카카오메일주소>.json.

A ferramenta MCP usa a estrutura que utiliza o access token do arquivo json.