MCP 服务器

Korea Tourism API MCP Server

使人工智能助手能够通过韩国旅游发展局官方API访问韩国旅游信息，从而提供对景点、活动、美食和住宿的全面搜索，并提供多语言支持。

README

韩国旅游 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 自动安装 Korea Tourism API MCP Server：

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 run -m mcp_tourism.server
```
服务器将启动并通过标准输入/输出 (stdio) 侦听 MCP 请求。

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

克隆仓库：

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

构建 Docker 镜像： 将 "YOUR_KTO_API_KEY" 替换为你获得的实际密钥。此命令使用提供的 Dockerfile 构建镜像，并将 API 密钥安全地作为构建参数传递。

>>> docker build -t mcp-korea-tourism-api .

[+] Building 2.7s (13/13) FINISHED                                                 docker:desktop-linux
=> [internal] load build definition from Dockerfile                                               0.0s
=> => transferring dockerfile: 1.46kB                                                             0.0s
=> resolve image config for docker-image://docker.io/docker/dockerfile:1                          0.9s
=> CACHED docker-image://docker.io/docker/dockerfile:1@sha256:4c68376a702446fc3c79af22de146a148b  0.0s
=> [internal] load metadata for docker.io/library/python:3.12-slim                                0.7s
=> [internal] load .dockerignore                                                                  0.0s
=> => transferring context: 864B                                                                  0.0s
=> [1/6] FROM docker.io/library/python:3.12-slim@sha256:85824326bc4ae27a1abb5bc0dd9e08847aa5fe73  0.0s
=> [internal] load build context                                                                  0.0s
=> => transferring context: 7.06kB                                                                0.0s
=> CACHED [2/6] RUN pip install --no-cache-dir uv                                                 0.0s
=> CACHED [3/6] WORKDIR /app                                                                      0.0s
=> CACHED [4/6] COPY pyproject.toml uv.lock ./                                                    0.0s
=> [5/6] RUN uv sync --frozen                                                                     0.8s
=> [6/6] COPY . .                                                                                 0.0s
=> exporting to image                                                                             0.1s
=> => exporting layers                                                                            0.1s
=> => writing image sha256:d7d074e85a66a257d00bad4043ea0f5ba8acf6b7c6ef26560c6904bf3ec4d5ff       0.0s
=> => naming to docker.io/library/mcp-korea-tourism                                               0.0s

>>> docker images

REPOSITORY                              TAG                IMAGE ID       CREATED          SIZE
mcp-korea-tourism                       latest             d7d074e85a66   12 seconds ago   215MB

-t mcp-korea-tourism-api：使用名称 mcp-korea-tourism-api 标记构建的镜像。
.：指定当前目录作为构建上下文。

运行 Docker 容器： 你可以以交互模式运行容器进行测试，或以分离模式运行容器进行后台操作。
- 交互模式（用于手动测试）：
```
docker run --rm -it -e KOREA_TOURISM_API_KEY="YOUR_KTO_API_KEY" mcp-korea-tourism-api
```
  - --rm：在容器退出时自动删除容器。
  - -it：以交互模式运行，将你的终端连接到容器的 stdio。
  - -e KOREA_TOURISM_API_KEY=...：在运行时设置 API 密钥环境变量（构建参数的替代方法）。
- 分离模式（用于后台）：
```
docker run --name tourism-mcp -d -e KOREA_TOURISM_API_KEY="YOUR_KTO_API_KEY" mcp-korea-tourism-api
```
  - --name tourism-mcp：为容器分配一个名称。
  - -d：以分离（后台）模式运行容器。
  - 你可以使用 docker logs tourism-mcp 查看日志。

🛠️ 与 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" 替换为你的实际密钥。 cursor_integrations

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

OR 使用 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"
            }
        }
    }
}