Kakao Bot Mcp Server

Kakao Bot MCP Server

• Kakao Bot MCP Server
• 例
• ツール
  • インストール
    • ステップ 1. developers.kakao.com で Kakao アプリケーションを作成
    • ステップ 2. ローカル環境の設定

Kakao Developers API を統合し、AI エージェントを Kakao Official Account に接続する Model Context Protocol (MCP) サーバーの実装です。

MCP サーバーの実装例で、Kakao Developers API を AI エージェントに統合します。

メモ

このリポジトリは Kakao が公式に提供または保守しているものではありません。
すべての機能が揃っているとは限らず、包括的なサポートも提供されない場合があります。
Kakao では、ほとんどの API の権限が事業者登録を含むビジネスアプリケーション単位で管理されているため、
個人での利用には制限があります。

参考ドキュメント：https://developers.kakao.com/docs/latest/ko/kakaotalk-message/rest-api

---

例

Claude デスクトップアプリで MCP ツールを実行

「自分にメッセージを送信」の結果

ツール

すべてのツールで、ユーザーの認証情報を特定するために __email_address__ 入力が必要です。

Kakao TalkMessage API

• 作成時点では、「自分に送信 - デフォルトテンプレート」API のみをサポートしています。
• 参考ドキュメント：https://developers.kakao.com/docs/latest/ko/kakaotalk-message/rest-api#default-template-msg-me

1. send_text_template_to_me

   • 説明：Kakao Talk のテキストメッセージを自分に送信します。
   • 入力：
     • __email_address__（string、必須）：Kakao アカウントに関連付けられたメールアドレス。
     • text（string、必須、最大 200 文字）：メッセージのテキスト内容。
     • link（object、必須）：テキストに関連付けるリンクを定義するオブジェクト。
       • web_url（string、任意、uri 形式）
       • mobile_web_url（string、任意、uri 形式）
     • button_title（string、任意）：ボタンのタイトル。

2. send_feed_template_to_me

   • 説明：Kakao Talk のフィードメッセージを自分に送信します。
   • 入力：
     • __email_address__（string、必須）
     • content（object、必須）：フィードメッセージのメインコンテンツブロック。
       • title（string、必須）
       • description（string、必須）
       • image_url（string、必須、uri 形式）
       • image_width（integer、任意）
       • image_height（integer、任意）
       • link（object、必須）：コンテンツのリンクを定義します
         • web_url（string、任意、uri 形式）
         • mobile_web_url（string、任意、uri 形式）
         • android_execution_params（string、任意）
         • ios_execution_params（string、任意）
     • item_content（object、任意）：フィードに追加するアイテムコンテンツ。（ネストされた構造については API ドキュメントを参照してください）
     • social（object、任意）：いいねやコメントなどのソーシャル情報。（ネストされた構造については API ドキュメントを参照してください）
     • buttons（object の array、任意）：メッセージに含めるボタン。（各オブジェクトには title と link が必要です）

3. **send_list_template_to_me** * 説明：自分にKakao Talkのリストメッセージを送信します。 * 入力： * `__email_address__`（string、必須） * `header_title`（string、必須）：リストの最上部に表示されるタイトルです。 * `contents`（array of objects、必須）：コンテンツ項目のリストです。各項目には次の情報が必要です。 * `title`（string、必須） * `description`（string、必須） * `image_url`（string、必須、uri形式） * `image_width`（integer、任意） * `image_height`（integer、任意） * `link`（object、必須）- リスト項目のリンクを定義します * `web_url`（string、任意、uri形式） * `mobile_web_url`（string、任意、uri形式） * `android_execution_params`（string、任意） * `ios_execution_params`（string、任意） * `header_link`（object、任意）：ヘッダー領域のリンクです。（ネストされた構造についてはAPIドキュメントを参照してください） * `buttons`（array of objects、任意）：メッセージに含めるボタンです。（各オブジェクトには`title`と`link`が必要です）

4. send_location_template_to_me

   • 説明：自分にKakao Talkの位置情報メッセージを送信します。
   • 入力：
     • __email_address__（string、必須）
     • content（object、必須）：位置情報メッセージのメインコンテンツブロックです。
       • title（string、必須）
       • description（string、必須）
       • image_url（string、必須、uri形式）
       • image_width（integer、任意）
       • image_height（integer、任意）
       • link（object、必須）- コンテンツのリンクを定義します
         • web_url（string、任意、uri形式）
         • mobile_web_url（string、任意、uri形式）
         • android_execution_params（string、任意）
         • ios_execution_params（string、任意）
     • address（string、必須）：位置情報の住所です。
     • buttons（array of objects、任意）：メッセージに含めるボタンです。（各オブジェクトにはtitleとlinkが必要です）
     • address_title（string、任意）：住所のタイトルです。

5. send_calendar_template_to_me

   • 説明：自分にKakao Talkのカレンダーメッセージを送信します。
   • 入力：
     • __email_address__（string、必須）
     • content（object、必須）：カレンダーメッセージのメインコンテンツブロックです。
       • title（string、必須）
       • description（string、必須）
       • link（object、必須）- コンテンツのリンクを定義します
         • web_url（string、任意、uri形式）
         • mobile_web_url（string、任意、uri形式）
         • android_execution_params（string、任意）
         • ios_execution_params（string、任意）
       • image_url（string、任意、uri形式）
     • id_type（string、必須、列挙値：「event」）：カレンダー項目の種類です。
     • id（string、必須）：カレンダー項目のIDです。
     • buttons（array of objects、任意）：メッセージに含めるボタンです。（各オブジェクトにはtitleとlinkが必要です）

6. send_commerce_template_to_me

   • Description: カカオトークのコマースメッセージを自分に送信します。
   • Inputs:
     • __email_address__ (string, required)
     • content (object, required): コマースメッセージのメインコンテンツブロックです。
       • title (string, required)
       • image_url (string, required, uri format)
       • image_width (integer, optional)
       • image_height (integer, optional)
       • link (object, required) - コンテンツのリンクを定義します
         • web_url (string, optional, uri format)
         • mobile_web_url (string, optional, uri format)
         • android_execution_params (string, optional)
         • ios_execution_params (string, optional)
     • commerce (object, required): コマース固有の情報です。
       • regular_price (integer, required)
       • discount_price (integer, optional)
       • discount_rate (integer, optional, 0-100)
     • buttons (array of objects, optional): メッセージに含めるボタンです。（各オブジェクトには title と link が必要です）

Kakao TalkCalendar API

• Kakao TalkCalendar API を使用して、ユーザーのカレンダーを確認・管理するツールです。
  • 執筆時点では、「ユーザーカレンダー - 一覧の取得、サブカレンダーの作成／更新／削除」機能のみをサポートしています。
  • TalkCalendar API を利用するには、カカオに使用権限を申請する必要があります。申請方法については、https://developers.kakao.com/docs/latest/ko/talkcalendar/common#policy-request-permission を参照してください。
• 参考ドキュメント：https://developers.kakao.com/docs/latest/ko/talkcalendar/rest-api

1. get_calendar_list

   • Description: ユーザーのカレンダー一覧を取得します。
   • Inputs:
     • __email_address__ (string, required): Kakao アカウントに関連付けられたメールアドレスです。

2. create_sub_calendar

   • Description: ユーザー用の新しいサブカレンダーを作成します。
   • Inputs:
     • __email_address__ (string, required): Kakao アカウントに関連付けられたメールアドレスです。
     • name (string, required): サブカレンダーの名前です。
     • color (string, optional): カレンダー内の予定に設定するデフォルトの色です。
     • reminder (integer, optional): 終日の予定以外に設定するデフォルトのリマインダー時間（分）です。
     • reminder_all_day (integer, optional): 終日の予定に設定するデフォルトのリマインダー時間（分）です。

3. update_sub_calendar

   • Description: 既存のサブカレンダーを更新します。
   • Inputs:
     • __email_address__ (string, required): Kakao アカウントに関連付けられたメールアドレスです。
     • calendar_id (string, required): 更新するサブカレンダーの ID です。
     • name (string, optional): サブカレンダーの新しい名前です。
     • color (string, optional): カレンダー内の予定に設定する新しいデフォルトの色です。
     • reminder (integer, optional): 終日の予定以外に設定する新しいデフォルトのリマインダー時間（分）です。
     • reminder_all_day (integer, optional): 終日の予定に設定する新しいデフォルトのリマインダー時間（分）です。

4. delete_sub_calendar

   • Description: ユーザーのサブカレンダーを削除します。
   • Inputs:
     • __email_address__ (string, required): Kakao アカウントに関連付けられたメールアドレスです。
     • calendar_id (string, required): 削除するサブカレンダーの ID です。

インストール

要件：Python 3.13+

カカオアカウントが必要です

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

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

메시지 API를 활성화하기 위한 추가작업

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

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

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

• 제품 설정 > 카카오 로그인 > 동의항목에서 '닉네임', '카카오계정(이메일)', '카카오톡 메시지 전송' 을 활성화한다.
• OpenID 활성화한다.
• 톡캘린더 API가 필요한 경우 https://developers.kakao.com/docs/latest/ko/talkcalendar/common#policy-request-permission 를 참고해서 사용 권한을 신청해야 한다.

Step 2. 로컬환경 설정

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

git clone [email protected]: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 경로에 아래 파일을 생성한다.

.accounts.json

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

• email: 카카오 계정 이메일주소.
• account_type: personal 고정.
• extra_info: MCP server에 전달할 추가정보.

.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: 카카오 애플리케이션에서 제공하는 REST_API key
• client_secret: 카카오 애플리케이션에서 발급받을 수 있는 client_secret. 임의의 문자열을 넣어도 동작함
• 나머지 필드는 고정.

claude desktop 설정

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

동작 방식

LLM이 MCP Tool을 실행하면

• 프로젝트 root 경로에 .oauth2.<카카오메일주소>.json 파일이 있는지 확인한다.
  • 파일이 없을 경우, 웹 브라우저에 카카오 OAuth2 서버에 로그인 화면을 띄운다. (https://accounts.kakao.com/login?continue=...)
  • 파일이 있을 경우, 토큰이 만료되지 않았는지 확인한다. 만료되었다면, refresh token으로 재발급받는다. refresh token도 만료되었을 경우, tool에서 로그인할 수 있는 url 주소를 리턴한다.
• 로그인에 성공하면, 프로젝트 root 경로에 .oauth2.<카카오메일주소>.json 이름으로 access_token 정보를 저장한다.

MCP tool은 json 파일의 access token을 사용하는 구조.