Korea Tourism API MCP Server

韩国旅游API MCP服务器✈️

](https://smithery.ai/interface/@harimkang/mcp-korea-tourism-api)  ](https://badge.fury.io/py/mcp-korea-tourism-api)  

直接在您的AI助手中解锁韩国旅游的奇迹！该项目提供了一个由官方韩国旅游组织（KTO）API提供支持的模型上下文协议（MCP）服务器。让你的人工智能能够发现韩国各地充满活力的节日、宁静的寺庙、美味的餐厅、舒适的住宿等等。

链接：

• PyPI包： https://pypi.org/project/mcp-korea-tourism-api/
• GitHub存储库：
• 发布：

✨ 特性

• 全面搜索： 通过关键字、地区或位置查找旅游景点、文化景点、活动、食物、住宿和购物。
• 丰富的细节： 访问说明、营业时间、入场费、照片、地址和联系信息。
• 位置感知： 探索特定GPS坐标附近的景点。
• 及时信息： 根据日期范围查找节日和活动。
• 多语言支持： 获取KTO API支持的各种语言的信息（包括英语）。

- 支持的语言：英语、日语、简体中文、繁体中文、俄语、西班牙语、德语、法语

• 高效且有弹性：

- 响应缓存： 使用生存时间（TTL）缓存来存储结果并减少冗余的API调用，从而提高速度。 - 速率限制： 遵守API使用限制，以防止出现错误。 - 自动检索： 在临时网络或服务器问题的情况下自动重试请求。

• MCP标准： 与支持模型上下文协议的AI助手无缝集成。

⚠️ 先决条件

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

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

🚀 安装与运行

您可以使用以下任一方式运行此MCP服务器 uv （一个快速的Python包安装程序和运行程序）或 Docker.

通过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

1. 设置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，或使用系统环境变量设置）。_

1. 安装依赖项并运行服务器：

此命令使用 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

1. 构建Docker镜像：

您可以使用不同的传输配置构建映像：

   # Default build (stdio transport)
   docker build -t mcp-korea-tourism-api .

   # Build with HTTP transport configuration
   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 \
     .

   # Build with SSE transport configuration
   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 \
     .

1. 运行Docker容器：

您可以使用不同的传输配置运行容器：

- 标准传输（默认值-适用于MCP客户端）：

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

- HTTP传输（用于web应用程序）：

     # Using runtime environment variables
     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

     # Check health: 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（推荐）：

     # Copy and configure environment variables
     cp docker.env.example .env
     # Edit .env file with your API key and preferred settings

     # Run with HTTP transport (default profile)
     docker-compose up mcp-tourism-http

     # Run with SSE transport
     docker-compose --profile sse up mcp-tourism-sse

     # Run development setup with debug logging
     docker-compose --profile dev up mcp-tourism-dev

🔧 传输配置

韩国旅游API MCP服务器支持多种传输协议，以适应不同的使用情况：

可用交通工具

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

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

1. streamable-http：基于HTTP的web应用程序传输

- 最适合：Web应用程序、REST API集成、负载平衡器 - 功能：HTTP端点、健康检查、JSON响应 - 默认端点： http://localhost:8000/mcp

1. sse：实时应用程序的服务器发送事件传输

- 最适合：实时web应用程序、事件驱动架构 - 特点：实时流媒体，持久连接 - 默认端点： http://localhost:8080/mcp

配置选项

您可以使用命令行参数或环境变量配置服务器：

命令行示例

# 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将执行此操作。

1. 找到您的 mcp.json 文件： 此文件为Cursor配置MCP工具。您通常可以通过Cursor的设置或可能在以下路径中找到它 ~/.cursor/mcp.json 或类似。

1. 添加或更新MCP配置： 将以下JSON对象添加到您的列表中 mcp.json 文件。如果您已经有此工具的条目，请更新其 command.更换 "YOUR_KTO_API_KEY" 用你真正的钥匙。

cursor_integrations

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

1. 保存 mcp.json.

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

🛠️ 提供的MCP工具

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

1. search_tourism_by_keyword：使用关键字搜索旅游信息（例如“景福宫”、“Bibimbap”）。按内容类型、区号过滤。

search_tourism_by_keyword

1. get_tourism_by_area：按地理区域代码浏览旅游信息（例如，首尔=“1”）。按内容类型、地区代码过滤。

get_tourism_by_area

1. find_nearby_attractions：发现特定GPS坐标（经度、纬度）附近的旅游景点。按半径和内容类型过滤。

find_nearby_attractions

1. search_festivals_by_date：查找在指定日期范围（YYYYMMDD）内发生的节日。按区号过滤。

search_festivals_by_date

1. find_accommodations：搜索酒店、宾馆等。按地区和地区代码过滤。

find_accommodations

1. get_detailed_information：使用内容ID检索特定项目的全面详细信息（概述、使用时间、停车等）。按内容类型筛选。

get_detailed_information

1. get_tourism_images：使用内容ID获取与特定旅游项目关联的图像URL。

get_tourism_images

1. get_area_codes：检索区号（城市/省份）和可选的分区（地区）代码。

get_area_codes

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

• Python 3.12+
• uv 已安装(pip install uv)

示例用法

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

• “查找明洞站附近的餐馆。”
• “给我看看Bulguksa寺的照片。”
• “下个月釜山有什么节日吗？”
• “告诉我更多关于景福宫的信息，内容ID 264337。”

](https://mseep.ai/app/harimkang-mcp-korea-tourism-api)