Kakao Bot MCP Gateway

This repository furnishes a concrete implementation of the Model Context Protocol (MCP) server specification, focusing on integrating the functionality exposed via the Kakao Developers API suite. This integration enables sophisticated bidirectional interaction between an intelligent agent and a designated Kakao Official Account.

• Kakao Bot MCP Gateway
• Demonstration
• Tool Definitions
• Setup Procedures
  • Phase 1. Application Registration on developers.kakao.com
  • Phase 2. Local Environment Configuration

This server serves as an architectural example of deploying an MCP endpoint tailored for Kakao services.

[!CAUTION] This particular codebase is developed independently and does not carry any official endorsement or maintenance commitment from Kakao Corp. Functionality completeness and support levels may vary. Note that many of Kakao's primary APIs mandate permissions tied to formally registered business entities, potentially limiting utility for individual developers.

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

---

Demonstration

Executing MCP tool via a desktop client (e.g., Claude Desktop)

Result of the 'Send Message to Myself' invocation

Tool Definitions

Authentication for all provided tools mandates the inclusion of the __email_address__ parameter to correctly resolve the invoking user's credentials.

Kakao Talk Message Dispatcher API

- Currently supports only the 'Send Message to Me - Basic Template' API as of this writing. - Reference: https://developers.kakao.com/docs/latest/ko/kakaotalk-message/rest-api#default-template-msg-me 1. **dispatch_text_message_to_self** * Description: Transmits a standard text-based Kakao Talk message directed to the authenticated user. * Inputs: * `__email_address__` (string, required): Identifier for the Kakao account credential. * `text` (string, required, maximum 200 characters): The textual content payload. * `link` (object, required): Structure defining the hyperlink associated with the message. * `web_url` (string, optional, URI format) * `mobile_web_url` (string, optional, URI format) * `button_title` (string, optional): Label for the accompanying hyperlink button. 2. **dispatch_feed_message_to_self** * Description: Sends a Kakao Talk feed-style message (rich card) to the user. * Inputs: * `__email_address__` (string, required) * `content` (object, required): Primary visual and descriptive elements. * `title` (string, required) * `description` (string, required) * `image_url` (string, required, URI format) * `image_width` (integer, optional) * `image_height` (integer, optional) * `link` (object, required) - Defines the target URI for the content block. * `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): Supplementary item details for richer content presentation. (Refer to official API schema). * `social` (object, optional): Metadata related to social metrics (e.g., likes, comments). (Refer to official API schema). * `buttons` (array of objects, optional): Interactive button elements. (Each requires `title` and `link`). 3. **dispatch_list_message_to_self** * Description: Sends a Kakao Talk message formatted as a vertically stacked list to the user. * Inputs: * `__email_address__` (string, required) * `header_title` (string, required): Title displayed prominently at the list header. * `contents` (array of objects, required): Array defining each list entry. Each entry requires: * `title` (string, required) * `description` (string, required) * `image_url` (string, required, URI format) * `image_width` (integer, optional) * `image_height` (integer, optional) * `link` (object, required) - Target URI for the list item. * `web_url` (string, optional, URI format) * `mobile_web_url` (string, optional, URI format) * `android_execution_params` (string, optional) * `ios_execution_params` (string, optional) * `header_link` (object, optional): A hyperlink target for the overall header section. * `buttons` (array of objects, optional): Action buttons appended below the list. 4. **dispatch_location_message_to_self** * Description: Dispatches a Kakao Talk message highlighting a specific geographical location. * Inputs: * `__email_address__` (string, required) * `content` (object, required): Core descriptive elements of the location card. * `title` (string, required) * `description` (string, required) * `image_url` (string, required, URI format) * `image_width` (integer, optional) * `image_height` (integer, optional) * `link` (object, required) - Target URI for the location card. * `web_url` (string, optional, URI format) * `mobile_web_url` (string, optional, URI format) * `android_execution_params` (string, optional) * `ios_execution_params` (string, optional) * `address` (string, required): The precise geographical address string. * `buttons` (array of objects, optional): Associated action buttons. * `address_title` (string, optional): Optional label prefixing the address display. 5. **dispatch_calendar_event_to_self** * Description: Sends a Kakao Talk message structured as a calendar event notification. * Inputs: * `__email_address__` (string, required) * `content` (object, required): Standard content block for the event card. * `title` (string, required) * `description` (string, required) * `link` (object, required) - Target URI for the event. * `web_url` (string, optional, URI format) * `mobile_web_url` (string, optional, URI format) * `android_execution_params` (string, optional) * `ios_execution_params` (string, optional) * `image_url` (string, optional, URI format) * `id_type` (string, required, enum: "event"): Specifies the item type being referenced. * `id` (string, required): The unique identifier corresponding to the calendar item. * `buttons` (array of objects, optional): Action buttons. 6. **dispatch_commerce_offer_to_self** * Description: Sends a Kakao Talk message structured for a product/commerce display. * Inputs: * `__email_address__` (string, required) * `content` (object, required): Product presentation details. * `title` (string, required) * `image_url` (string, required, URI format) * `image_width` (integer, optional) * `image_height` (integer, optional) * `link` (object, required) - Target URI for the product. * `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): Pricing information. * `regular_price` (integer, required): The base price. * `discount_price` (integer, optional): The price after any reduction. * `discount_rate` (integer, optional, range 0-100) * `buttons` (array of objects, optional): Call-to-action buttons.

Kakao Talk Calendar Management API

- This module interfaces with the Kakao Talk Calendar API to enable query and manipulation of the user's calendar data. - Currently implemented scope covers 'User Calendar - Retrieve List, Create/Modify/Remove Sub-Calendars'. - Access to the Talk Calendar API requires prior authorization approval from Kakao. See: https://developers.kakao.com/docs/latest/ko/talkcalendar/common#policy-request-permission - Reference: https://developers.kakao.com/docs/latest/ko/talkcalendar/rest-api 1. **query_user_calendar_list** * Description: Fetches the registry of calendars associated with the user. * Inputs: * `__email_address__` (string, required): Credential identifier for the Kakao account. 2. **instantiate_sub_calendar** * Description: Provisions a new ancillary calendar for the user. * Inputs: * `__email_address__` (string, required): Credential identifier for the Kakao account. * `name` (string, required): The designated label for the new calendar. * `color` (string, optional): The default visual hue for calendar entries. * `reminder` (integer, optional): Default alert duration in minutes for standard (non-all-day) events. * `reminder_all_day` (integer, optional): Default alert duration in minutes for all-day events. 3. **modify_sub_calendar** * Description: Applies updates to an already existing ancillary calendar. * Inputs: * `__email_address__` (string, required): Credential identifier for the Kakao account. * `calendar_id` (string, required): The unique identifier of the target calendar. * `name` (string, optional): The proposed renaming. * `color` (string, optional): The revised default color scheme. * `reminder` (integer, optional): New default minute offset for non-all-day event notifications. * `reminder_all_day` (integer, optional): New default minute offset for all-day event notifications. 4. **decommission_sub_calendar** * Description: Permanently removes a user-created sub-calendar. * Inputs: * `__email_address__` (string, required): Credential identifier for the Kakao account. * `calendar_id` (string, required): The identifier of the sub-calendar slated for deletion.

Setup Procedures

Prerequisite: Python environment version 3.13 or newer.

Kakao Account required for authentication.

Phase 1. Application Registration on developers.kakao.com

Refer to the quick start guide for initial application creation steps.

Supplemental Configuration for Message API Enablement

 Under "My Application > App Settings > Platform," register the host domain as `http://localhost:8000` under the Web platform settings.
 Register as a Biz App. Business registration is not mandatory; registration as a 'Individual Developer Biz App' is supported.
 Activate Kakao Login functionality.
 - Under Product Settings > Kakao Login > Consent Items, enable 'Nickname', 'Kakao Account (Email)', and 'KakaoTalk Message Sending'. - Activate OpenID. - If Talk Calendar API usage is required, follow the instructions at https://developers.kakao.com/docs/latest/ko/talkcalendar/common#policy-request-permission to request necessary permissions.

Phase 2. Local Environment Configuration

Ensure uv is installed in your local Python environment.

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

Launch the inspector utility

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

Initiate the MCP gateway server

uv run mcp-kakao

For successful operation, two essential configuration files must reside 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 actual email address linked to your Kakao account.
• account_type: Fixed value: personal.
• extra_info: Optional metadata to be conveyed to the MCP server context.

.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 provided by your Kakao application settings.
• client_secret: The application-specific client secret. (A placeholder string may suffice for local testing).
• All other fields must remain static.

Claude Desktop Configuration Snippet

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

Operational Flow

When the LLM invokes an MCP Tool: - The system checks the project root for a file named .oauth2.<kakao_email_address>.json. - If the file is absent, the Kakao OAuth2 login interface is opened in a web browser (URL similar to https://accounts.kakao.com/login?continue=...). - If the file exists, token validity is verified. If the access token has expired, a refresh attempt is made. If the refresh token is also invalid, the tool returns a direct URL allowing the user to log in via the browser. - Upon successful user authentication, the acquired access token information is persisted locally under the filename .oauth2.<kakao_email_address>.json.

The MCP tool architecture is fundamentally dependent on retrieving these locally stored JSON access tokens for subsequent API calls.