使用说明

项目简介

本项目是一个基于 Model Context Protocol (MCP) 构建的服务器，旨在通过标准化的 MCP 协议，向大型语言模型 (LLM) 客户端提供韩国流行的 Kakao 地图 API 和 Daum 搜索 API 的访问能力。它允许 LLM 应用利用 Kakao 地图的地理位置服务和 Daum 搜索引擎的信息检索功能，扩展 LLM 的上下文理解和外部交互能力。

主要特点：

MCP 协议兼容： 完全遵循 MCP 协议规范，易于与任何 MCP 客户端集成。
Kakao 地图 API 集成： 提供地点搜索、坐标转地址、路线规划等地图相关工具。
Daum 搜索 API 集成： 提供网页、图片、博客、咖啡馆等多种搜索工具。
多种运行模式： 支持 HTTP 和 Stdio 两种传输协议，灵活适应不同的部署环境。
详细日志记录： 提供完善的请求和响应日志，方便调试和监控。

主要功能点

本项目提供以下工具 (Tools)，供 LLM 客户端调用：

Kakao 地图 API 工具：

地点搜索 (search-places)： 根据关键词在 Kakao 地图中搜索地点，返回地点名称、地址、类别、联系方式、详细信息链接等。
坐标转地址 (coord-to-address)： 将经纬度坐标转换为韩国地址，提供道路名地址和地号地址。
路线规划 (find-route)： 规划从出发地到目的地的路线，支持汽车、公共交通、步行等多种方式，提供距离、所需时间、预计出租车费用等信息，并可选择包含交通信息。

Daum 搜索 API 工具：

网页搜索 (search-web)： 在 Daum 搜索引擎中搜索网页文档，支持按相关度和最新时间排序，可调整每页结果数和页码。
图片搜索 (search-image)： 在 Daum 搜索引擎中搜索图片，支持按相关度和最新时间排序，可调整每页结果数和页码。
博客搜索 (search-blog)： 在 Daum 搜索引擎中搜索博客文章，支持按相关度和最新时间排序，可调整每页结果数和页码，返回博客名称、文章标题、内容摘要等。
咖啡馆搜索 (search-cafe)： 在 Daum 搜索引擎中搜索 Daum Cafe 文章，支持按相关度和最新时间排序，可调整每页结果数和页码，返回咖啡馆名称、帖子标题、内容摘要等。

安装步骤

克隆仓库:

git clone https://github.com/jeong-sik/kakao-api-mcp-server.git
cd kakao-api-mcp-server

安装依赖:

yarn install

或者使用 npm:

npm install

配置 Kakao REST API 密钥:
- 访问 Kakao开发者网站，创建应用并获取 REST API 密钥。
- 在项目根目录下创建 '.env' 文件。
- 在 '.env' 文件中添加以下内容，将 'YOUR_KAKAO_REST_API_KEY' 替换为您的 Kakao REST API 密钥：
```
KAKAO_REST_API_KEY=YOUR_KAKAO_REST_API_KEY
```
- 或者，您也可以在运行服务器时通过命令行参数 '--kakao-api-key' 传入密钥。

服务器配置 (MCP 客户端)

MCP 客户端需要配置以下信息以连接到 Kakao/Daum API MCP 服务器。以下是 JSON 格式的配置示例，请根据您选择的运行模式进行配置：

1. HTTP 模式配置 (默认端口 3000):

{
  "serverName": "kakao-api-mcp-server",
  "command": "yarn",
  "args": ["start"],
  "transport": {
    "type": "sse",
    "url": "http://localhost:3000/sse",
    "postUrl": "http://localhost:3000/messages"
  }
}

HTTP 模式配置说明:

'serverName': 服务器名称，可以自定义。
'command': 启动服务器的命令，这里使用 'yarn'。如果使用 npm，则改为 'npm'。
'args': 启动命令的参数，'start' 对应 'package.json' 中的 'start' 脚本。
'transport.type': 传输协议类型，HTTP 模式使用 'sse' (Server-Sent Events)。
'transport.url': SSE 连接的 URL，默认为 'http://localhost:3000/sse'。
'transport.postUrl': POST 消息的 URL，默认为 'http://localhost:3000/messages'。

如果您需要更改 HTTP 端口，例如改为 8080，则配置如下:

{
  "serverName": "kakao-api-mcp-server",
  "command": "yarn",
  "args": ["start", "--port", "8080"],
  "transport": {
    "type": "sse",
    "url": "http://localhost:8080/sse",
    "postUrl": "http://localhost:8080/messages"
  }
}

2. Stdio 模式配置:

{
  "serverName": "kakao-api-mcp-server",
  "command": "yarn",
  "args": ["start:stdio"],
  "transport": {
    "type": "stdio"
  }
}

Stdio 模式配置说明:

'serverName': 服务器名称，可以自定义。
'command': 启动服务器的命令，这里使用 'yarn'。如果使用 npm，则改为 'npm'。
'args': 启动命令的参数，'start:stdio' 对应 'package.json' 中的 'start:stdio' 脚本，用于启动 Stdio 模式。
'transport.type': 传输协议类型，Stdio 模式使用 'stdio'。
'transport.url' 和 'transport.postUrl': Stdio 模式不需要 URL 配置。

Kakao REST API 密钥配置:

无论使用 HTTP 模式还是 Stdio 模式，Kakao REST API 密钥都可以通过以下两种方式配置：

环境变量 (.env 文件): 如安装步骤 3 所述，在 '.env' 文件中设置 'KAKAO_REST_API_KEY' 环境变量。

命令行参数: 在 'args' 数组中添加 '--kakao-api-key YOUR_KAKAO_REST_API_KEY' 参数。例如，HTTP 模式下使用命令行参数配置密钥：

{
  "serverName": "kakao-api-mcp-server",
  "command": "yarn",
  "args": ["start", "--kakao-api-key", "YOUR_KAKAO_REST_API_KEY"],
  "transport": {
    "type": "sse",
    "url": "http://localhost:3000/sse",
    "postUrl": "http://localhost:3000/messages"
  }
}

或 Stdio 模式下：

{
  "serverName": "kakao-api-mcp-server",
  "command": "yarn",
  "args": ["start:stdio", "--kakao-api-key", "YOUR_KAKAO_REST_API_KEY"],
  "transport": {
    "type": "stdio"
  }
}

基本使用方法

启动服务器:
- 根据您的 MCP 客户端配置，选择合适的模式 (HTTP 或 Stdio) 启动服务器。
- HTTP 模式: 在项目根目录下运行 'yarn start' 或 'npm start'。
- Stdio 模式: 在项目根目录下运行 'yarn start:stdio' 或 'npm run start:stdio'。
在 MCP 客户端中配置并连接到服务器。

通过 MCP 客户端向服务器发送工具调用请求。 例如，使用 'search-places' 工具搜索 "강남역 맛집" 的请求 JSON 格式如下：

{
  "type": "tool_call",
  "tool_name": "search-places",
  "parameters": {
    "keyword": "강남역 맛집"
  }
}

服务器将处理请求，调用 Kakao/Daum API，并将结果以 MCP 响应格式返回给客户端。 客户端接收并解析响应，即可获取工具执行结果。

请注意:

您需要拥有有效的 Kakao REST API 密钥才能使用此服务器。
服务器默认运行在开发模式，可能需要根据实际部署环境进行调整。
详细的 API 使用限制和计费规则请参考 Kakao开发者网站。

关键词