kakao-bot-mcp-server
If you are the rightful owner of kakao-bot-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
Model Context Protocol (MCP) server implementation that integrates the Kakao Developers API to connect an AI Agent to the Kakao Official Account.
Kakao Bot MCP Server
Model Context Protocol (MCP) server implementation that integrates the Kakao Developers API to connect an AI Agent to the Kakao Official Account.
MCP Server ๊ตฌํ์ฒด๋ก, ์นด์นด์ค Developers API๋ฅผ AI Agent์ ํตํฉํ๋ ์์์ ๋๋ค.
[!NOTE] This repository is NOT officially provided or maintained by Kakao.
It may not include complete functionality or comprehensive support.
์นด์นด์ค์ ๊ฒฝ์ฐ ๋๋ถ๋ถ์ API๊ฐ ์ฌ์ ์๋ฑ๋ก์ด ํฌํจ๋ ๋น์ฆ๋์ค ์ ํ๋ฆฌ์ผ์ด์ ๋จ์๋ก ๊ถํ์ ๊ด๋ฆฌํ๊ณ ์์ผ๋ฏ๋ก,
๊ฐ์ธ์ด ์ฌ์ฉํ๊ธฐ์ ์ ํ์ ์ ๋๋ค.
์ฐธ๊ณ ๋ฌธ์: https://developers.kakao.com/docs/latest/ko/kakaotalk-message/rest-api
์์

claude desktop์ผ๋ก MCP tool ์คํ

'๋์๊ฒ ๋ฉ์์ง ์ ๋ฌ' ๊ฒฐ๊ณผ
Tools
All tools require the __email_address__
input to identify the user's credentials.
Kakao TalkMessage API
- ์์ฑ์์ ๊ธฐ์ค, '๋์๊ฒ ๋ณด๋ด๊ธฐ - ๊ธฐ๋ณธ ํ ํ๋ฆฟ' API๋ง ์ง์๋ฉ๋๋ค.
- ์ฐธ๊ณ ๋ฌธ์: https://developers.kakao.com/docs/latest/ko/kakaotalk-message/rest-api#default-template-msg-me
-
send_text_template_to_me
- Description: Sends a Kakao Talk text message to me.
- Inputs:
__email_address__
(string, required): The email address associated with the Kakao account.text
(string, required, max 200 characters): The text content of the message.link
(object, required): An object defining the link associated with the text.web_url
(string, optional, uri format)mobile_web_url
(string, optional, uri format)
button_title
(string, optional): The title of the button.
-
send_feed_template_to_me
- Description: Sends a Kakao Talk feed message to me.
- Inputs:
__email_address__
(string, required)content
(object, required): The main content block of the feed message.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 link for the contentweb_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): Additional item content for the feed. (See API documentation for nested structure)social
(object, optional): Social information like likes, comments, etc. (See API documentation for nested structure)buttons
(array of objects, optional): Buttons to include with the message. (Each object requirestitle
andlink
)
-
send_list_template_to_me
- Description: Sends a Kakao Talk list message to me.
- Inputs:
__email_address__
(string, required)header_title
(string, required): The title displayed at the top of the list.contents
(array of objects, required): A list of content items. Each item requires: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 link for the list itemweb_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 link for the header area. (See API documentation for nested structure)buttons
(array of objects, optional): Buttons to include with the message. (Each object requirestitle
andlink
)
-
send_location_template_to_me
- Description: Sends a Kakao Talk location message to me.
- Inputs:
__email_address__
(string, required)content
(object, required): The main content block for the location message.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 link for the contentweb_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 address of the location.buttons
(array of objects, optional): Buttons to include with the message. (Each object requirestitle
andlink
)address_title
(string, optional): A title for the address.
-
send_calendar_template_to_me
- Description: Sends a Kakao Talk calendar message to me.
- Inputs:
__email_address__
(string, required)content
(object, required): The main content block for the calendar message.title
(string, required)description
(string, required)link
(object, required) - defines the link for the contentweb_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"): The type of calendar item.id
(string, required): The ID of the calendar item.buttons
(array of objects, optional): Buttons to include with the message. (Each object requirestitle
andlink
)
-
send_commerce_template_to_me
- Description: Sends a Kakao Talk commerce message to me.
- Inputs:
__email_address__
(string, required)content
(object, required): The main content block for the commerce message.title
(string, required)image_url
(string, required, uri format)image_width
(integer, optional)image_height
(integer, optional)link
(object, required) - defines the link for the contentweb_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): Commerce-specific information.regular_price
(integer, required)discount_price
(integer, optional)discount_rate
(integer, optional, 0-100)
buttons
(array of objects, optional): Buttons to include with the message. (Each object requirestitle
andlink
)
Kakao TalkCalendar API
- ์นด์นด์ค ํก์บ๋ฆฐ๋ API๋ฅผ ํตํด ์ฌ์ฉ์์ ์บ๋ฆฐ๋๋ฅผ ์กฐํํ๊ณ ๊ด๋ฆฌํ๋ ๋๊ตฌ์
๋๋ค.
- ์์ฑ์์ ๊ธฐ์ค '์ฌ์ฉ์ ์บ๋ฆฐ๋ - ๋ชฉ๋ก ๊ฐ์ ธ์ค๊ธฐ, ์๋ธ ์บ๋ฆฐ๋ ์์ฑ / ์์ / ์ญ์ ' ๊ธฐ๋ฅ๋ง ์ง์๋ฉ๋๋ค.
- ํก์บ๋ฆฐ๋ API๋ ์นด์นด์ค์ ์ฌ์ฉ ๊ถํ์ ์ ์ฒญํด์ผ ํฉ๋๋ค. ์ ์ฒญ ๋ฐฉ๋ฒ์ https://developers.kakao.com/docs/latest/ko/talkcalendar/common#policy-request-permission ๋ฅผ ์ฐธ๊ณ ํ์ธ์.
- ์ฐธ๊ณ ๋ฌธ์: https://developers.kakao.com/docs/latest/ko/talkcalendar/rest-api
-
get_calendar_list
- Description: Retrieves the list of user calendars.
- Inputs:
__email_address__
(string, required): The email address associated with the Kakao account.
-
create_sub_calendar
- Description: Creates a new sub-calendar for the user.
- Inputs:
__email_address__
(string, required): The email address associated with the Kakao account.name
(string, required): The name of the sub calendar.color
(string, optional): The default color for events in the calendar.reminder
(integer, optional): The default reminder time for non-all-day events in minutes.reminder_all_day
(integer, optional): The default reminder time for all-day events in minutes.
-
update_sub_calendar
- Description: Updates an existing sub-calendar.
- Inputs:
__email_address__
(string, required): The email address associated with the Kakao account.calendar_id
(string, required): The ID of the sub calendar to update.name
(string, optional): The new name for the sub calendar.color
(string, optional): The new default color for events in the calendar.reminder
(integer, optional): The new default reminder time for non-all-day events in minutes.reminder_all_day
(integer, optional): The new default reminder time for all-day events in minutes.
-
delete_sub_calendar
- Description: Deletes a user's sub-calendar.
- Inputs:
__email_address__
(string, required): The email address associated with the Kakao account.calendar_id
(string, required): The ID of the sub calendar to delete.
installation
requirements: 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 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
์ ์์ ์ผ๋ก ๋์ํ๋ ค๋ฉด ๋ ๊ฐ์ ํ์ผ์ด ํ์ํ๋ค. .accounts.json
, .kauth.json
ํ๋ก์ ํธ root ๊ฒฝ๋ก์ ์๋ ํ์ผ์ ์์ฑํ๋ค.
.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: ์นด์นด์ค ๊ณ์ ์ด๋ฉ์ผ์ฃผ์.
- 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์ ์ฌ์ฉํ๋ ๊ตฌ์กฐ.