KKT-Integration-Gateway-Server

This repository furnishes a reference implementation of an MCP intermediary service, specifically designed to tether an artificial intelligence agent to the Kakao ecosystem by leveraging the Kakao Developers API capabilities.

• KKT-Integration-Gateway-Server
• Demonstrative Use Cases
• Exposed Utilities
• Prerequisites & Setup
  • Phase 1. Kakao Developer Application Provisioning
  • Phase 2. Local Environment Configuration

[!WARNING] This software package is neither officially endorsed nor maintained by Kakao Corp. Functionality completeness and ongoing support are not guaranteed. Due to Kakao's authorization structure, which often mandates business registration for extensive API access, individual developers may encounter operational constraints.

Reference Documentation: Kakao Talk Message REST API

---

Demonstrative Use Cases

Initiating the MCP utility via the Claude desktop environment.

Result of executing the 'Send Message to Self' operation.

Exposed Utilities

All utility functions mandate the __email_address__ input parameter to authenticate against the user's designated credentials.

Kakao TalkMessage Interfaces

*Note: At the time of development, only the 'Send to Myself - Basic Template' API is implemented.* *Reference: [Kakao Talk Message API - Default Template](https://developers.kakao.com/docs/latest/ko/kakaotalk-message/rest-api#default-template-msg-me) 1. **send_text_template_to_me** * **Description:** Transmits a Kakao Talk message containing simple text content directly to the user. * **Inputs:** * `__email_address__` (string, mandatory): Identifier corresponding to the Kakao account. * `text` (string, mandatory, max 200 UTF-8 characters): The primary textual payload. * `link` (object, mandatory): URL structure for the message interaction. * `web_url` (string, optional, URI format) * `mobile_web_url` (string, optional, URI format) * `button_title` (string, optional): Label displayed on the associated interactive button. 2. **send_feed_template_to_me** * **Description:** Dispatches a richer, feed-style Kakao Talk notification to the user. * **Inputs:** * `__email_address__` (string, mandatory) * `content` (object, mandatory): Core visual and textual elements. * `title` (string, mandatory) * `description` (string, mandatory) * `image_url` (string, mandatory, URI format) * `image_width` (integer, optional) * `image_height` (integer, optional) * `link` (object, mandatory): Destination links. * `web_url` (string, optional, URI format) * `mobile_web_url` (string, optional, URI format) * `android_execution_params` (string, optional) * `ios_execution_params` (string, optional) * `item_content` (object, optional): Supplemental structured data blocks (Refer to official Kakao API spec). * `social` (object, optional): Metadata regarding engagement metrics (Refer to official Kakao API spec). * `buttons` (array of objects, optional): Interactive actions. (Each requires `title` and `link`). 3. **send_list_template_to_me** * **Description:** Sends a notification formatted as a navigable list of items to the user. * **Inputs:** * `__email_address__` (string, mandatory) * `header_title` (string, mandatory): Title text for the list header section. * `contents` (array of objects, mandatory): Array defining each list entry. (Each object requires `title`, `description`, `image_url`, and `link`). * `header_link` (object, optional): Link attached to the overall header area. * `buttons` (array of objects, optional): Actions displayed at the bottom. 4. **send_location_template_to_me** * **Description:** Delivers a notification presenting geographical location details. * **Inputs:** * `__email_address__` (string, mandatory) * `content` (object, mandatory): Primary message content block. * `address` (string, mandatory): The specific geographical coordinates or textual address. * `buttons` (array of objects, optional): Action buttons. * `address_title` (string, optional): Custom label for the address field. 5. **send_calendar_template_to_me** * **Description:** Sends a message notifying the user about a specific calendar event. * **Inputs:** * `__email_address__` (string, mandatory) * `content` (object, mandatory): Event description block. * `id_type` (string, mandatory, must be "event"): Specifies the item type being referenced. * `id` (string, mandatory): The unique identifier for the calendar entry. * `buttons` (array of objects, optional): Action buttons. 6. **send_commerce_template_to_me** * **Description:** Sends a message optimized for presenting product or commerce-related information. * **Inputs:** * `__email_address__` (string, mandatory) * `content` (object, mandatory): Product visual details. * `commerce` (object, mandatory): Pricing specifics. * `regular_price` (integer, mandatory): Original selling price. * `discount_price` (integer, optional) * `discount_rate` (integer, optional, range 0-100) * `buttons` (array of objects, optional): Purchase or detail links.

Kakao TalkCalendar Interfaces

This interface enables querying and modifying the user's Kakao Talk Calendar data. * **Current Scope:** Supports retrieving the user's calendar manifest, and creating, modifying, or deleting *sub-calendars* only. * **Prerequisite:** Access to the TalkCalendar API necessitates formal permission application via Kakao Developers: [Permission Request Guide](https://developers.kakao.com/docs/latest/ko/talkcalendar/common#policy-request-permission). - **Reference:** [Kakao TalkCalendar REST API](https://developers.kakao.com/docs/latest/ko/talkcalendar/rest-api) 1. **get_calendar_list** * **Description:** Fetches the inventory of calendars accessible to the authenticated user. * **Inputs:** * `__email_address__` (string, mandatory): Account identifier. 2. **create_sub_calendar** * **Description:** Provisions a new auxiliary calendar under the user's profile. * **Inputs:** * `__email_address__` (string, mandatory) * `name` (string, mandatory): Desired name for the new calendar. * `color` (string, optional): Default visual theme color. * `reminder` (integer, optional): Default pre-event notification time (in minutes) for standard events. * `reminder_all_day` (integer, optional): Default pre-event notification time (in minutes) for all-day events. 3. **update_sub_calendar** * **Description:** Modifies the configuration of an existing auxiliary calendar. * **Inputs:** * `__email_address__` (string, mandatory) * `calendar_id` (string, mandatory): Unique identifier of the target calendar. * `name` (string, optional): New designation. * `color` (string, optional): New color setting. * `reminder` (integer, optional): Updated reminder setting for standard events. * `reminder_all_day` (integer, optional): Updated reminder setting for all-day events. 4. **delete_sub_calendar** * **Description:** Permanently removes a specified auxiliary calendar. * **Inputs:** * `__email_address__` (string, mandatory) * `calendar_id` (string, mandatory): Identifier of the calendar slated for removal.

Prerequisites & Setup

Required runtime environment: Python version 3.13 or newer.

Requires an active Kakao developer account.

Phase 1. Kakao Developer Application Provisioning

Consult the official quick start guide for initial application creation steps.

Mandatory Post-Creation Configuration for Messaging API

 Under "My Application > App Settings > Platform", register `http://localhost:8000` as the allowed Web site domain.
 Register as a 'Personal Developer Biz App'. This registration is permitted even without a registered business number.
 Enable the Kakao Login feature.
 * In 'Product Settings > Kakao Login > Consent Items', enable 'Nickname', 'Kakao Account (Email)', and 'KakaoTalk Message Sending'. * Activate OpenID. * If TalkCalendar APIs are required, follow the guidelines at [this link](https://developers.kakao.com/docs/latest/ko/talkcalendar/common#policy-request-permission) to request necessary usage permissions.

Phase 2. Local Environment Configuration

Ensure that the uv package manager is installed locally.

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

Start the Inspector service

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

Launch the primary MCP server

uv run mcp-kakao

Successful operation requires two configuration files to be present in the project root directory: .accounts.json and .kauth.json.

.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: The registered email address for the Kakao account.
• account_type: Must be set statically to personal.
• extra_info: Optional context data passed to the MCP server layer.

.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: The REST_API key obtained from your Kakao application dashboard.
• client_secret: The client secret generated by Kakao (setting it to any string will often allow initial operation, but proper key usage is recommended).
• Other fields should remain constant.

Claude Desktop Integration Configuration

Ensure the following configuration is present in your Claude client's settings file:

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

Authentication Flow Description

When an LLM invokes an MCP Utility:

1. The server checks the project root for a token file named .oauth2.<kakao_email>.json.
   • If absent, the system initiates the Kakao OAuth2 login sequence in the user's default web browser (redirecting to a URL similar to https://accounts.kakao.com/login?...).
   • If present, the system validates the stored access_token. If expired, it attempts renewal using the stored refresh_token. If the refresh token has also expired, the tool signals the LLM by returning a URL link that facilitates manual token acquisition.
2. Upon successful user authorization, the server persists the newly obtained access_token information into the .oauth2.<kakao_email>.json file.

The fundamental operational model of this MCP utility relies on securing and utilizing these JSON-stored access tokens for subsequent API calls.