Content
# Kakao API MCP Server
This is a server that allows you to utilize Kakao Map API and Daum Search API through [Model Context Protocol](https://github.com/anthropics/model-context-protocol) (MCP). Through this server, AI models can utilize Kakao Map's map-related functions and Daum's various search functions.
## Precautions
* **User account-related functions such as Kakao Login and sending KakaoTalk messages are not included.** This server only uses publicly available Kakao and Daum Open APIs.
* To use this server, you need a valid **Kakao REST API key**. Create an app at [Kakao Developers](https://developers.kakao.com/) and get a REST API key.
## Main Features
### Kakao Map API
1. **Place Search (`mcp_kakao_map_search_places`)**
- Search for places on Kakao Map by keyword
- Provides location, category, and contact information
2. **Coordinate-to-Address Conversion (`mcp_kakao_map_coord_to_address`)**
- Convert latitude and longitude coordinates to actual addresses
- Provides road name address and lot number address information
3. **Find Route (`mcp_kakao_map_find_route`)**
- Search for routes from origin to destination
- Provides distance, travel time, estimated taxi fare, etc.
- Includes traffic information (optional)
### Daum Search API
1. **Web Document Search (`mcp_kakao_map_search_web`)**
- Search Daum web documents by keyword
- Can adjust page sorting and number of search results
2. **Image Search (`mcp_kakao_map_search_image`)**
- Search Daum images by keyword
- Provides image URL and related information
3. **Blog Search (`mcp_kakao_map_search_blog`)**
- Search Daum blog posts by keyword
- Provides blog name, post title, and content summary
4. **Cafe Search (`mcp_kakao_map_search_cafe`)**
- Search Daum cafe posts by keyword
- Provides cafe name, post title, and content summary
## Example Usage (MCP)
Below are examples of how an MCP client (e.g., an AI model) calls the tools of this server and the expected response format.
### Kakao Map API
#### 1. Place Search (`mcp_kakao_map_search_places`)
**Request:**
```json
{
"tool_name": "mcp_kakao_map_search_places",
"parameters": {
"keyword": "판교역 현대백화점"
}
}
```
**Response (Example):**
```json
{
"tool_name": "mcp_kakao_map_search_places",
"result": "장소 검색 결과 (결과 수: 15, 총 18개):\n이름: 현대백화점 판교점\n주소: 경기 성남시 분당구 백현동 541\n카테고리: 쇼핑,유통 > 백화점 > 현대백화점\n전화번호: 031-5170-2233\n상세정보: http://place.map.kakao.com/18757447\n---\n... (추가 결과)"
}
```
#### 2. Coordinate-to-Address Conversion (`mcp_kakao_map_coord_to_address`)
**Request:**
```json
{
"tool_name": "mcp_kakao_map_coord_to_address",
"parameters": {
"x": 127.1120278,
"y": 37.3955833
}
}
```
**Response (Example):**
```json
{
"tool_name": "mcp_kakao_map_coord_to_address",
"result": "주소 변환 결과:\n도로명: 경기 성남시 분당구 판교역로146번길 20\n지번: 경기 성남시 분당구 백현동 535"
}
```
#### 3. Find Route (`mcp_kakao_map_find_route`)
**Request:**
```json
{
"tool_name": "mcp_kakao_map_find_route",
"parameters": {
"origin": "판교역",
"destination": "정자역",
"transportation_type": "car",
"traffic_info": true
}
}
```
**Response (Example):**
```json
{
"tool_name": "mcp_kakao_map_find_route",
"result": "🗺️ 길찾기 결과\n\n출발지: 판교역 신분당선 (경기 성남시 분당구 삼평동)\n\n목적지: 정자역 신분당선 (경기 성남시 분당구 정자동)\n\n이동 수단: 자동차\n\n총 거리: 3.6km\n예상 소요 시간: 10분\n예상 택시 요금: 5,600원\n\n📊 교통 상황 요약:\n\n카카오맵에서 보기: https://map.kakao.com/?sName=%ED%8C%90%EA%B5%90%EC%97%AD&eName=%EC%A0%95%EC%9E%90%EC%97%AD\n"
}
```
### Daum Search API
#### 1. Web Document Search (`mcp_kakao_map_search_web`)
**Request:**
```json
{
"tool_name": "mcp_kakao_map_search_web",
"parameters": {
"query": "카카오브레인 칼로",
"size": 2
}
}
```
**Response (Example):**
```json
{
"tool_name": "mcp_kakao_map_search_web",
"result": "웹 문서 검색 결과 (총 2083개 중 2개 표시):\n\n1. 카카오브레인 | 칼로 Karlo\n 내용: 카카오브레인의 이미지 생성 모델 Karlo는 사용자가 입력한 문장(Text)을 이해하여, 세상에 단 하나뿐인 이미지를 만들어내는 인공지능 화가입니다. 수백만 장 규모의...\n URL: https://kakaobrain.com/karlo\n 날짜: 2024. 1. 1.\n\n2. 카카오브레인, AI 아티스트 '칼로 2.0' 공개 - 테크레시피\n 내용: 카카오브레인이 초거대 인공지능(AI) 이미지 생성 모델 '칼로(Karlo) 2.0'을 공개했다고 11일 밝혔다. 칼로 2.0은 약 3억 장 규모의 텍스트-이미지 데이터셋을 학습한 모델이...\n URL: https://techrecipe.co.kr/posts/56513\n 날짜: 2023. 7. 11.\n\n현재 페이지가 마지막 페이지가 아닙니다. 더 많은 결과를 보려면 page 매개변수를 증가시키세요.\n"
}
```
#### 2. Image Search (`mcp_kakao_map_search_image`)
**Request:**
```json
{
"tool_name": "mcp_kakao_map_search_image",
"parameters": {
"query": "고양이",
"size": 1
}
}
```
**Response (Example):**
```json
{
"tool_name": "mcp_kakao_map_search_image",
"result": "이미지 검색 결과 (총 8715385개 중 1개 표시):\n\n1. 컬렉션 이름: Daum 백과\n 문서 URL: http://100.daum.net/encyclopedia/view/172XX61300001\n 이미지 URL: https://t1.daumcdn.net/thumb/R1024x0/?fname=http%3A%2F%2Ft1.daumcdn.net%2Fencyclop%2F172%2F613%2F172XX61300001\n 썸네일 URL: https://search1.kakaocdn.net/thumb/R100x100/?fname=http%3A%2F%2Ft1.daumcdn.net%2Fencyclop%2F172%2F613%2F172XX61300001&token=1579057346066cfd0b2e0c671d07c433\n 크기: 가로 1024px, 세로 682px\n 표시 URL: 100.daum.net\n 날짜: 2014. 11. 6.\n\n현재 페이지가 마지막 페이지가 아닙니다. 더 많은 결과를 보려면 page 매개변수를 증가시키세요.\n"
}
```
#### 3. Blog Search (`mcp_kakao_map_search_blog`)
**Request:**
```json
{
"tool_name": "mcp_kakao_map_search_blog",
"parameters": {
"query": "판교 맛집",
"size": 1
}
}
```
**Response (Example):**
```json
{
"tool_name": "mcp_kakao_map_search_blog",
"result": "블로그 검색 결과 (총 215893개 중 1개 표시):\n\n1. 블로그명: 짱돌의 일상다반사\n 제목: 판교 맛집 추천 | 유스페이스몰 가성비 좋은 점심 맛집\n 내용: 판교테크노밸리 유스페이스몰은 늘 점심시간마다 직장인들로 인산인해를 이루는 곳이다. 오늘은 판교 점심 맛집으로 괜찮은 곳 두 군데를 소개해 본다. 1.... \n URL: http://jdcamping.tistory.com/1374\n 썸네일: https://search2.kakaocdn.net/thumb/R180x180/?fname=https%3A%2F%2Fblog.kakaocdn.net%2Fdn%2FcQv0tX%2FbtrOfR4oUu3%2FdKQGkK0kY6kKk40f4kYkYK%2Fimg.jpg&token=1c251bb24ae4bb01657303012e2641ac\n 날짜: 2024. 12. 17.\n\n현재 페이지가 마지막 페이지가 아닙니다. 더 많은 결과를 보려면 page 매개변수를 증가시키세요.\n"
}
```
#### 4. Cafe Search (`mcp_kakao_map_search_cafe`)
**Request:**
```json
{
"tool_name": "mcp_kakao_map_search_cafe",
"parameters": {
"query": "코딩 스터디",
"size": 1
}
}
```
**Response (Example):**
```json
{
"tool_name": "mcp_kakao_map_search_cafe",
"result": "카페 검색 결과 (총 18335개 중 1개 표시):\n\n1. 카페명: 독취사-취업,대학생,대기업,공기업,NCS,인적성,취업카페\n 제목: [스터디] 웹개발/코딩 기초 스터디 구해요\n 내용: 안녕하세요! 웹개발 및 코딩 기초를 함께 공부할 스터디원을 모집합니다. 현재 2명이며, 최대 4명까지 생각하고 있습니다. 장소는 주로 강남/사당에서 진행하고, 온라...\n URL: http://cafe.daum.net/breakjob/DldL/12345\n 썸네일: https://search1.kakaocdn.net/thumb/P180x180/?fname=https%3A%2F%2Ft1.daumcdn.net%2Fcafe_image%2F%2Fconfig%2Fimg_default_profile%3Fver%3D1&token=de43b9d06222d0a2192f9f70fcb0f134\n 날짜: 2025. 3. 28.\n\n현재 페이지가 마지막 페이지가 아닙니다. 더 많은 결과를 보려면 page 매개변수를 증가시키세요.\n"
}
```
## Installation and Setup
1. **Clone the repository and install dependencies:**
```bash
git clone https://github.com/yousleepwhen/kakao-api-mcp-server.git # Please change the repository URL to the actual URL
cd kakao-api-mcp-server
yarn install
```
* This project recommends using the `yarn` package manager.
2. **Set Kakao REST API Key:**
- Create a `.env` file in the project root directory.
- Enter the REST API key issued by Kakao Developers in the `.env` file as follows:
```
KAKAO_REST_API_KEY=여기에_카카오_REST_API_키_입력
```
- Alternatively, you can pass it directly through the `--kakao-api-key` argument when running the server.
## How to Run
Before running the server, you need to build the code. Since the `start` related script includes the build process, you do not need to run `yarn build` separately.
### HTTP Mode (Default)
Used when communicating with other services or tools via HTTP.
```bash
yarn start
```
It uses port 3000 by default. To change the port, use the `--port` argument:
```bash
yarn start --port 8080
```
### stdio Mode
Used to exchange MCP messages through the terminal's standard input/output (stdin/stdout).
```bash
yarn start:stdio
```
### Development Mode
If you want to automatically build and restart the server when the code changes during development (separate settings such as nodemon are required), you can use the `dev` script. Currently, the `dev` script works the same as `start`.
```bash
yarn dev
```
## License
This project is distributed under the MIT license.
