使用说明

韩国旅游API MCP服务器✈️

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

链接：

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助手无缝集成。

⚠️ 先决条件

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

访问 KTO 数据门户（或旅游API的特定门户网站（如果可用）。
注册并请求“TourAPI”服务的API密钥（您可能需要查找提供以下信息的服务 areaBasedList, searchKeyword, detailCommon等等）。
保持你的 服务密钥（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` （建议当地开发）

克隆存储库：

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

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

安装依赖项并运行服务器： 此命令使用 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（推荐用于隔离环境/部署）

克隆存储库：

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

构建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 \
  .

运行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服务器支持多种传输协议，以适应不同的使用情况：

可用交通工具

stdio （默认）：用于直接MCP客户端集成的标准输入/输出传输
- 最适合：Claude Desktop、Cursor和其他兼容MCP的AI助手
- 配置：无需额外设置
streamable-http：基于HTTP的web应用程序传输
- 最适合：Web应用程序、REST API集成、负载平衡器
- 功能：HTTP端点、健康检查、JSON响应
- 默认端点： http://localhost:8000/mcp
sse：实时应用程序的服务器发送事件传输
- 最适合：实时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服务器：

确保Docker容器可运行： 按照上面的Docker安装步骤构建镜像(mcp-korea-tourism-api).您不需要手动运行容器；Cursor将执行此操作。
找到您的 mcp.json 文件： 此文件为Cursor配置MCP工具。您通常可以通过Cursor的设置或可能在以下路径中找到它 ~/.cursor/mcp.json 或类似。

添加或更新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"
      }
    }
  }
}

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

🛠️ 提供的MCP工具

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

search_tourism_by_keyword：使用关键字搜索旅游信息（例如“景福宫”、“Bibimbap”）。按内容类型、区号过滤。
get_tourism_by_area：按地理区域代码浏览旅游信息（例如，首尔=“1”）。按内容类型、地区代码过滤。
find_nearby_attractions：发现特定GPS坐标（经度、纬度）附近的旅游景点。按半径和内容类型过滤。
search_festivals_by_date：查找在指定日期范围（YYYYMMDD）内发生的节日。按区号过滤。
find_accommodations：搜索酒店、宾馆等。按地区和地区代码过滤。
get_detailed_information：使用内容ID检索特定项目的全面详细信息（概述、使用时间、停车等）。按内容类型筛选。
get_tourism_images：使用内容ID获取与特定旅游项目关联的图像URL。
get_area_codes：检索区号（城市/省份）和可选的分区（地区）代码。

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

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

示例用法

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

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

使用说明

韩国旅游API MCP服务器✈️

✨ 特性

⚠️ 先决条件

🚀 安装与运行

通过Smithery安装

选项1：使用 uv （建议当地开发）

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

🔧 传输配置

可用交通工具

配置选项

命令行示例

环境变量示例

健康检查

🛠️ 与Cursor集成

🛠️ 提供的MCP工具

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

示例用法

相关 MCP

百度地图

地图服务接口

代码索引分析工具

滴滴出行MCP服务

AIGoHotel(酒店预订）

地图API服务

选项1：使用 `uv` （建议当地开发）

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