getyourguide-mcp

getyourguide-mcp

适用于 GetYourGuide 的 MCP 服务——通过 GetYourGuide Partner API 搜索旅游和活动、查看旅游详情、可预订选项及评价。

🤖 本项目由 AI（Claude Code）开发并维护。 请自行斟酌使用。

• npm： npmjs.com/package/getyourguide-mcp
• 源代码： github.com/chrischall/getyourguide-mcp

工具

所有工具均为只读工具——此服务不会注册任何写入工具。

工具	功能
gyg_search_tours	按自由文本、地点、类别或日期范围搜索旅游/活动；支持排序；view
gyg_get_tour	按数字 ID 获取某项旅游的完整记录；view
gyg_get_tour_options	获取某项旅游的可预订选项（票种、时间），可选指定日期范围；view
gyg_get_tour_availability	获取某项旅游的预订可用情况：参与者类别、附加项目、可选日期；view
gyg_get_tour_reviews	获取某项旅游的客户评价；view
gyg_list_categories	活动类别（ID 可用于 gyg_search_tours / gyg_list_category_tours）；view
gyg_list_category_tours	获取某一类别下的旅游；view
gyg_get_location	按 ID 获取地点（城市、POI、地区）的详情；view
gyg_list_location_tours	获取某一地点提供的旅游；view
gyg_healthcheck	验证凭据和上游连接情况；以数据而非异常的形式报告故障

view — 响应结构

每个数据工具都接受 view: "compact" | "full"，且默认值为 compact。效率不应成为需要主动请求的选项，因此它不是可选开启的功能——gyg_search_tours 上旧的 compact: true 标志已移除。

• compact — 对三个旅游列表工具，返回文档所述的精简投影（tour_id、title、abstract、url、price、overall_rating、number_of_ratings、durations、categories、locations），并整理为 { _metadata, tours }。对 gyg_get_tour——它只返回一条记录，没有可供投影的列表封装——以及其他所有工具（选项、可用情况、评价、类别、地点），则会移除图片 URL，并保留其他所有内容。
• full — 原样返回 GetYourGuide 完整的校验后记录。

当你需要投影中未包含的字段（图片变体、坐标、营销文案）时，使用 full。无论哪种模式，所有响应都是经过压缩的 JSON：会移除格式化空白，但值内部的空白不会被移除。

设置

你需要一个 GetYourGuide Partner API 密钥——加入免费的合作伙伴计划 partner.getyourguide.com，并从控制面板复制 API 密钥。每次请求都会通过 X-ACCESS-TOKEN 标头发送该密钥。

Claude Code / 任意 MCP 宿主

{
  "mcpServers": {
    "getyourguide": {
      "command": "npx",
      "args": ["-y", "getyourguide-mcp"],
      "env": {
        "GYG_API_KEY": "your-partner-api-key"
      }
    }
  }
}

即使未设置密钥，服务也能启动（以便宿主在安装时查询 tools/list）；首次调用工具时会返回可操作的错误，告知你需要设置哪个环境变量。

环境变量

变量	必需	含义
GYG_API_KEY	是（调用工具时）	Partner API 密钥，通过 X-ACCESS-TOKEN 发送
GYG_CURRENCY	否	价格的默认货币（ISO 4217；默认使用 USD——API 要求必须提供）；单次调用中的 currency 参数会覆盖此值
GYG_LANGUAGE	否	内容的默认语言（默认使用 en——API 要求必须提供）；单次调用中的 language 参数会覆盖此值
GYG_BASE_URL	否	API 基础 URL（默认值为 https://api.getyourguide.com/1）
GYG_REQUEST_TIMEOUT_MS	否	单次请求的超时时间（默认值为 30000）

本地开发时，将这些变量放入服务旁边的 .env 文件中（该文件已加入 gitignore；参见 .env.example）。

行为说明

• **速率限制：**遇到 429/503 时会自动重试一次，并遵循 Retry-After （最多等待 10s）。如果仍然失败，错误会提示你降低请求频率。
• **超时和网络故障：**请求超过 GYG_REQUEST_TIMEOUT_MS，或未能到达 API（DNS、连接被拒绝、连接重置）， 会作为工具错误返回，并指出请求路径，同时提示你延长超时时间，或检查 GYG_BASE_URL 和网络。取消调用不会被包装——它仍然是取消操作。
• **空参数：**空字符串查询参数（例如 currency: "" 或 language: ""）会被丢弃，而不会发送，因此会采用环境变量默认值 / USD / en 回退值，避免 API 因空值而拒绝请求。
• 身份验证错误：401/403 会指出两种可能的原因——密钥错误，或 密钥所属的合作伙伴等级不支持该端点。
• **API 变更：**响应会经过宽松验证。如果响应形状不符合预期，服务会向 stderr 记录明确的警告，并返回原始响应，而不是报错。参见 docs/GETYOURGUIDE-API.md—— 路由和请求形状已针对 API 及其官方 OpenAPI 规范进行实时验证；实际的 200 响应正文仍需通过使用密钥的抓取进行固定。
• extraParams：gyg_search_tours 和 gyg_get_tour_options 接受 extraParams，用于传递架构中未定义的原始查询参数。与工具自身参数（limit、offset、 currency、cnt_language、q 等）冲突的键会被忽略——始终以类型化参数或 其默认值为准。（在 2.1.6 之前，extraParams 会覆盖这些参数。）
• **密钥：**上游错误正文会先脱敏再截断，然后才会传入工具结果；API 密钥绝不会被回显。

开发

npm install
npm run build          # tsc + esbuild bundle → dist/
npm test               # tsc typecheck + vitest (no network — everything mocked)
npm run test:coverage  # tsc typecheck + the CI gate: 100% lines/branches/functions/statements

发布由 release-please 自动完成；不要手动提升版本号。PR 标题必须使用规范提交格式（feat:、fix: 等），因为仓库会采用 squash 合并。

许可证

MIT