Korea Tourism API MCP Server

韩国旅游 API MCP 服务 ✈️

直接在 AI 助手中探索韩国旅游的精彩之处！本项目提供由韩国旅游发展局（KTO）官方 API 驱动的模型上下文协议（MCP）服务。为 AI 赋予探索韩国各地精彩节庆、静谧寺庙、美味餐馆、舒适住宿等内容的能力。

链接：

• PyPI 软件包： https://pypi.org/project/mcp-korea-tourism-api/
• GitHub 仓库： https://github.com/harimkang/mcp-korea-tourism-api
• 发行版本： https://github.com/harimkang/mcp-korea-tourism-api/releases

✨ 功能特性

• 全面搜索： 按关键词、地区或位置查找旅游景点、文化遗址、活动、美食、住宿和购物场所。
• 丰富详情： 获取介绍、营业时间、门票费用、照片、地址和联系信息。
• 位置感知： 探索特定 GPS 坐标附近的景点。
• 及时信息： 按日期范围查找节庆和活动。
• 多语言支持： 获取 KTO API 支持的多种语言信息（包括英语）。
  • 支持的语言：英语、日语、简体中文、繁体中文、俄语、西班牙语、德语、法语
• 高效且可靠：
  • 响应缓存： 使用生存时间（TTL）缓存存储结果，减少重复 API 调用，提升速度。
  • 速率限制： 遵守 API 使用限制，避免错误。
  • 自动重试： 遇到临时网络或服务问题时自动重试请求。
• MCP 标准： 与支持模型上下文协议的 AI 助手无缝集成。

⚠️ 前提条件

开始之前，必须从韩国旅游发展局（KTO）数据门户获取 API 密钥。

1. 访问 KTO 数据门户（或旅游 API 的专属门户，如有）。
2. 注册并为“TourAPI”服务申请 API 密钥（可能需要查找提供 areaBasedList、searchKeyword、detailCommon 等信息的服务）。
3. 妥善保管你的服务密钥（API 密钥）。安装或运行时需要用到它。

你需要申请以下 API，才能获取对应语言的数据。

• 英语：https://www.data.go.kr/data/15101753/openapi.do
• 日语：https://www.data.go.kr/data/15101760/openapi.do
• 简体中文：https://www.data.go.kr/data/15101764/openapi.do
• 繁体中文：https://www.data.go.kr/data/15101769/openapi.do
• 俄语：https://www.data.go.kr/data/15101831/openapi.do
• 西班牙语：https://www.data.go.kr/data/15101811/openapi.do
• 德语：https://www.data.go.kr/data/15101805/openapi.do
• 法语：https://www.data.go.kr/data/15101808/openapi.do

🚀 安装与运行

你可以使用 uv（快速的 Python 软件包安装器和运行器）或 Docker 运行此 MCP 服务。

通过 Smithery 安装

通过 Smithery 自动为 Claude Desktop 安装韩国旅游 API MCP 服务：

npx -y @smithery/cli install @harimkang/mcp-korea-tourism-api --client claude

选项 1：使用 uv（推荐用于本地开发）

1. 克隆代码仓库：

   git clone https://github.com/harimkang/mcp-korea-tourism-api.git
   cd mcp-korea-tourism-api
   

2. 设置 API 密钥环境变量： 将 "YOUR_KTO_API_KEY" 替换为你获取的实际密钥。

   # On macOS/Linux
   export KOREA_TOURISM_API_KEY="YOUR_KTO_API_KEY"
   
   # On Windows (Command Prompt)
   # set KOREA_TOURISM_API_KEY="YOUR_KTO_API_KEY"
   
   # On Windows (PowerShell)
   # $env:KOREA_TOURISM_API_KEY="YOUR_KTO_API_KEY"
   

   注意：如需持久保存，请将此行添加到 shell 配置文件（例如 .zshrc、.bashrc），或使用系统环境变量设置。

3. 安装依赖并运行服务： 此命令使用 uv 根据 uv.lock（如果存在）或 pyproject.toml 安装依赖，然后运行服务模块。

   # Install Dependency with uv
   uv sync
   
   # Default: stdio transport (for MCP clients)
   uv run -m mcp_tourism.server
   
   # HTTP transport for web applications
   uv run -m mcp_tourism.server --transport streamable-http --host 127.0.0.1 --port 8000
   
   # SSE transport for real-time applications
   uv run -m mcp_tourism.server --transport sse --host 127.0.0.1 --port 8080
   
   # Using environment variables
   export MCP_TRANSPORT=streamable-http
   export MCP_HOST=0.0.0.0
   export MCP_PORT=3000
   uv run -m mcp_tourism.server
   

   服务将启动，并通过指定的传输协议监听 MCP 请求。

选项 2：使用 Docker（推荐用于隔离环境／部署）

1. 克隆代码库：

   git clone https://github.com/harimkang/mcp-korea-tourism-api.git
   cd mcp-korea-tourism-api
   

2. 构建 Docker 镜像： 你可以使用不同的传输配置来构建镜像：

   # 默认构建（stdio 传输）
   docker build -t mcp-korea-tourism-api .
   
   # 使用 HTTP 传输配置构建
   docker build -t mcp-korea-tourism-api \
     --build-arg MCP_TRANSPORT=streamable-http \
     --build-arg MCP_HOST=0.0.0.0 \
     --build-arg MCP_PORT=8000 \
     --build-arg MCP_PATH=/mcp \
     --build-arg MCP_LOG_LEVEL=INFO \
     .
   
   # 使用 SSE 传输配置构建
   docker build -t mcp-korea-tourism-api \
     --build-arg MCP_TRANSPORT=sse \
     --build-arg MCP_HOST=0.0.0.0 \
     --build-arg MCP_PORT=8080 \
     .
   

3. 运行 Docker 容器： 你可以使用不同的传输配置来运行容器：

   • Stdio 传输（默认，用于 MCP 客户端）：

     docker run --rm -it \
       -e KOREA_TOURISM_API_KEY="YOUR_KTO_API_KEY" \
       mcp-korea-tourism-api
     

   • HTTP 传输（用于 Web 应用）：

     # 使用运行时环境变量
     docker run --rm -p 8000:8000 \
       -e KOREA_TOURISM_API_KEY="YOUR_KTO_API_KEY" \
       -e MCP_TRANSPORT=streamable-http \
       -e MCP_HOST=0.0.0.0 \
       -e MCP_PORT=8000 \
       mcp-korea-tourism-api
     
     # 检查运行状态：curl http://localhost:8000/health
     

   • SSE 传输（用于实时应用）：

     docker run --rm -p 8080:8080 \
       -e KOREA_TOURISM_API_KEY="YOUR_KTO_API_KEY" \
       -e MCP_TRANSPORT=sse \
       -e MCP_HOST=0.0.0.0 \
       -e MCP_PORT=8080 \
       mcp-korea-tourism-api
     

   • 使用 Docker Compose（推荐）：

     # 复制并配置环境变量
     cp docker.env.example .env
     # 使用你的 API 密钥和首选设置编辑 .env 文件
     
     # 使用 HTTP 传输运行（默认配置）
     docker-compose up mcp-tourism-http
     
     # 使用 SSE 传输运行
     docker-compose --profile sse up mcp-tourism-sse
     
     # 运行带有调试日志的开发配置
     docker-compose --profile dev up mcp-tourism-dev
     

🔧 传输配置

Korea Tourism API MCP Server 支持多种传输协议，以满足不同的使用场景：

可用的传输方式

1. stdio（默认）：标准输入／输出传输，用于直接集成 MCP 客户端

   • 最适合：Claude Desktop、Cursor 和其他兼容 MCP 的 AI 助手
   • 配置：无需额外设置

2. streamable-http：基于 HTTP 的传输，用于 Web 应用

   • 最适合：Web 应用、REST API 集成、负载均衡器
   • 功能：HTTP 端点、运行状况检查、JSON 响应
   • 默认端点：http://localhost:8000/mcp

3. sse：Server-Sent Events 传输，用于实时应用

   • 最适合：实时 Web 应用、事件驱动架构
   • 功能：实时流式传输、持久连接
   • 默认端点：http://localhost:8080/mcp

配置选项

你可以通过命令行参数或环境变量配置服务：

设置	CLI 参数	环境变量	默认值	描述
传输方式	--transport	MCP_TRANSPORT	stdio	要使用的传输协议
主机	--host	MCP_HOST	127.0.0.1	HTTP 传输方式的主机地址
端口	--port	MCP_PORT	8000	HTTP 传输方式的端口
路径	--path	MCP_PATH	/mcp	HTTP 端点的路径
日志级别	--log-level	MCP_LOG_LEVEL	INFO	日志级别

命令行示例

# Get help for all available options
python -m mcp_tourism.server --help

# Run with HTTP transport on custom port
python -m mcp_tourism.server --transport streamable-http --port 3000 --log-level DEBUG

# Run with SSE transport
python -m mcp_tourism.server --transport sse --host 0.0.0.0 --port 8080

环境变量示例

# Set environment variables
export MCP_TRANSPORT=streamable-http
export MCP_HOST=0.0.0.0
export MCP_PORT=8000
export MCP_LOG_LEVEL=INFO
export KOREA_TOURISM_API_KEY="your_api_key_here"

# Run the server
python -m mcp_tourism.server

健康检查

对于 HTTP 和 SSE 传输方式，可通过 /health 使用健康检查端点：

# Check server health
curl http://localhost:8000/health

# Example response
{
  "status": "healthy",
  "service": "Korea Tourism API MCP Server",
  "transport": "streamable-http",
  "timestamp": 1640995200.0
}

🛠️ 与 Cursor 集成

要在 Cursor 中使用此 MCP 服务：

1. 确保 Docker 容器可运行： 按照上面的 Docker 安装步骤构建镜像（mcp-korea-tourism-api）。你无需手动运行容器；Cursor 会负责运行。

2. 找到你的 mcp.json 文件： 此文件用于配置 Cursor 的 MCP 工具。通常可以在 Cursor 的设置中找到，也可能位于 ~/.cursor/mcp.json 或类似路径。

3. 添加或更新 MCP 配置： 将以下 JSON 对象添加到 mcp.json 文件中的列表。如果已有此工具的条目，请更新其 command。将 "YOUR_KTO_API_KEY" 替换为你的实际密钥。

   {
     "mcpServers": {
       "korea-tourism": {
         "command": "docker",
         "args": [
           "run",
           "--rm",
           "-i",
           "-e",
           "KOREA_TOURISM_API_KEY=YOUR_KTO_API_KEY",
           "mcp-korea-tourism-api"
         ]
       }
     }
   }
   

   或者使用 uv [本地目录]

   {
     "mcpServers": {
       "korea-tourism": {
         "command": "uv",
         "args": [
           "--directory",
           "{LOCAL_PATH}/mcp-korea-tourism-api",
           "run",
           "-m",
           "mcp_tourism.server"
         ],
         "env": {
           "KOREA_TOURISM_API_KEY": "YOUR_KTO_API_KEY"
         }
       }
     }
   }
   

4. 保存 mcp.json。

5. 重启 Cursor 或重新加载 MCP 工具： Cursor 现在应该可以检测到该工具，并在需要时使用 Docker 运行它。

🛠️ 提供的 MCP 工具

此服务为 AI 助手提供以下工具：

1. search_tourism_by_keyword：使用关键词搜索旅游信息（例如 “Gyeongbokgung”“Bibimbap”）。可按内容类型和区域代码筛选。
2. get_tourism_by_area：按地理区域代码浏览旅游信息（例如，首尔 =“1”）。可按内容类型和区县代码筛选。
3. find_nearby_attractions：查找特定 GPS 坐标（经度、纬度）附近的旅游景点。可按半径和内容类型筛选。
4. search_festivals_by_date：查找指定日期范围（YYYYMMDD）内举办的节庆活动。可按区域代码筛选。
5. find_accommodations：搜索酒店、民宿等。可按区域和区县代码筛选。
6. get_detailed_information：使用内容 ID 获取特定项目的详细信息（概览、使用时间、停车等）。可按内容类型筛选。
7. get_tourism_images：使用内容 ID 获取与特定旅游项目相关的图片 URL。
8. get_area_codes：获取区域代码（城市／省份），也可选择获取子区域（区县）代码。

⚙️ 要求（适用于 uv 方式）

• Python 3.12+
• 已安装 uv（pip install uv）

使用示例

集成了此 MCP 的 AI 助手可以处理以下查询：

• “查找明洞站附近的餐厅。”
• “给我看看佛国寺的图片。”
• “下个月釜山有节庆活动吗？”
• “详细介绍一下景福宫，内容 ID 为 264337。”