MCP韩国旅游API服务器

Name: MCP韩国旅游API服务器
Author: harimkang

作者：harimkang7 星标更新：2025-08-12

安装使用来源：spider==github.com

项目介绍

韩国旅游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密钥。

访问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

🚀 安装与运行

您可以使用uv(一个快速的Python包安装器和运行器)或Docker来运行此MCP服务器。

通过Smithery安装

要通过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"替换为您实际获得的密钥。
```
# 在macOS/Linux上
export KOREA_TOURISM_API_KEY="YOUR_KTO_API_KEY"

# 在Windows(命令提示符)上
# set KOREA_TOURISM_API_KEY="YOUR_KTO_API_KEY"

# 在Windows(PowerShell)上
# $env:KOREA_TOURISM_API_KEY="YOUR_KTO_API_KEY"
```
注意：为了持久存储，请将此行添加到您的shell配置文件中（例如，.zshrc、.bashrc，或者使用系统环境变量设置）。

安装依赖项并运行服务器： 此命令使用uv基于uv.lock（如果可用）或pyproject.toml安装依赖项，然后运行服务器模块。

# 使用uv安装依赖项
uv sync

# 默认：stdio传输（适用于MCP客户端）
uv run -m mcp_tourism.server

# HTTP传输，适用于Web应用程序
uv run -m mcp_tourism.server --transport streamable-http --host 127.0.0.1 --port 8000

# SSE传输，适用于实时应用程序
uv run -m mcp_tourism.server --transport sse --host  127.0.0.1 --port 8080

# 使用环境变量
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镜像： 您可以使用不同的传输配置构建镜像：

# 默认构建(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 \
  .

运行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
# 编辑.env文件，填写您的API密钥和首选设置

# 使用HTTP传输（默认配置文件）
docker-compose up mcp-tourism-http

# 使用SSE传输
docker-compose --profile sse up mcp-tourism-sse

# 开发设置，带调试日志
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`	日志级别

命令行示例

# 获取所有可用选项的帮助
python -m mcp_tourism.server --help

# 使用自定义端口的HTTP传输运行
python -m mcp_tourism.server --transport streamable-http --port 3000 --log-level DEBUG

# 使用SSE传输运行
python -m mcp_tourism.server --transport sse --host 0.0.0.0 --port 8080

环境变量示例

# 设置环境变量
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"

# 运行服务器
python -m mcp_tourism.server

健康检查

对于HTTP和SSE传输，健康检查端点位于/health：

# 检查服务器健康状况
curl http://localhost:8000/health

# 示例响应
{
  "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配置： 在您的mcp.json文件列表中添加以下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"
      }
    }
  }
}