Kakao

This MCP server integrates the Kakao Developers API to connect an AI Agent to the Kakao Official Account, enabling you to send Kakao Talk messages and manage Kakao Talk Calendar content through an MCP client. It includes setup steps, OAuth configuration, and example tool endpoints that the agent can invoke.

How to use

You run the MCP tool to start the Kakao MCP server and connect it to your MCP client. The server exposes a set of Kakao TalkMessage API endpoints and Kakao TalkCalendar API endpoints that your AI Agent can call to send messages, calendars, and other content to your Kakao account. You will authenticate using an OAuth token flow and provide your Kakao account email to identify credentials for each operation.

How to install

Prerequisites: Python 3.13+, uv runtime, and network access to Kakao APIs.

Step 1. Create Kakao Application and configure APIs to enable Message API and, if needed, TalkCalendar API. For web platform, register http://localhost:8000 as a site domain and enable Kakao Login with required consent items. If you need TalkCalendar permissions, apply for access.

Step 2. Local environment setup. Install the MCP server locally and prepare OAuth credentials and accounts file.

# Install and run the MCP server locally
pip install uv
uv sync

# Inspect the project for MCP setup (optional in your environment)
npx @modelcontextprotocol/inspector uv --directory .  run mcp-kakao

# Start the MCP Kakao server
uv run mcp-kakao

Configuration and example files

You provide your Kakao account credentials and OAuth details through two JSON files in the project root. The server uses these to authenticate and access Kakao APIs on your behalf.

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

.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"
  }
}

Claude desktop configuration

Configure Claude to run the MCP Kakao server using the following MCP server definition.

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

How the system runs

When the MCP tool runs, it looks for an access token file tied to your Kakao account in the project root. If the file is missing, it opens a Kakao OAuth2 login page in your browser to obtain an access token. If a token exists but is expired, it attempts to refresh it. If refresh fails, it provides you with a login URL to reauthenticate. Once login succeeds, the access token is stored in the project root with a name derived from your Kakao email.

Available tools

send_text_template_to_me

Sends a Kakao Talk text message to the authenticated user using a template. Requires __email_address__ and a text content with optional link and button.

send_feed_template_to_me

Sends a Kakao Talk feed message to the authenticated user with main content, image, and optional buttons and links.

send_list_template_to_me

Sends a Kakao Talk list message to the authenticated user with a header and a list of items, each with title, description, and image.

send_location_template_to_me

Sends a Kakao Talk location message to the authenticated user with a title, description, image, and address details.

send_calendar_template_to_me

Sends a Kakao Talk calendar message to the authenticated user with a calendar item, image, and associated links.

send_commerce_template_to_me

Sends a Kakao Talk commerce message to the authenticated user with product details and a purchase link.

get_calendar_list

Retrieves the list of user calendars from Kakao TalkCalendar API for the specified account.

create_sub_calendar

Creates a new sub-calendar for the authenticated Kakao account with options for name, color, and reminders.

update_sub_calendar

Updates the properties of an existing sub-calendar for the authenticated Kakao account.

delete_sub_calendar

Deletes a specified sub-calendar from the authenticated Kakao account.