getyourguide-mcp

MCP server for GetYourGuide — search tours and activities, read tour details, bookable options, and reviews via the GetYourGuide Partner API.

🤖 This project was developed and is maintained by AI (Claude Code). Use at your own discretion.

npm: npmjs.com/package/getyourguide-mcp
Source: github.com/chrischall/getyourguide-mcp

Tools

All tools are read-only — this server registers no write tools.

Tool	What it does
`gyg_search_tours`	Search tours/activities by free text, location, category, or date range; sortable; `view`
`gyg_get_tour`	Full record for one tour by numeric ID; `view`
`gyg_get_tour_options`	Bookable options of a tour (ticket types, times), optionally within a date range; `view`
`gyg_get_tour_availability`	Booking availability of a tour: participant categories, addons, available dates; `view`
`gyg_get_tour_reviews`	Customer reviews for a tour; `view`
`gyg_list_categories`	Activity categories (IDs feed `gyg_search_tours` / `gyg_list_category_tours`); `view`
`gyg_list_category_tours`	Tours in one category; `view`
`gyg_get_location`	Details for a location (city, POI, region) by ID; `view`
`gyg_list_location_tours`	Tours available at one location; `view`
`gyg_healthcheck`	Verify credentials and upstream reachability; reports failures as data, not exceptions

`view` — response shape

Every data tool takes view: "compact" | "full", and compact is the default. An efficiency that has to be asked for is one that usually is not, so it is not opt-in — the old compact: true flag on gyg_search_tours is gone.

compact — on the three tour LISTINGS it returns the documented slim projection (tour_id, title, abstract, url, price, overall_rating, number_of_ratings, durations, categories, locations), flattened to { _metadata, tours }. On gyg_get_tour — one record, no listing envelope to project — and on every other tool (options, availability, reviews, categories, location) — it instead strips image URLs and keeps everything else.
full — GetYourGuide's whole validated record, untouched.

Reach for full when you need a field the projection does not carry (picture variants, coordinates, marketing copy). Every response is minified JSON either way: formatting whitespace is dropped, whitespace inside a value is not.

Setup

You need a GetYourGuide Partner API key — join the (free) partner program at partner.getyourguide.com and copy the API key from your dashboard. The key is sent as the X-ACCESS-TOKEN header on every request.

Claude Code / any MCP host

json

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

The server also boots with no key set (so hosts can probe tools/list at install time); the first tool call then returns an actionable error telling you which env var to set.

Environment variables

Variable	Required	Meaning
`GYG_API_KEY`	yes (for tool calls)	Partner API key, sent as `X-ACCESS-TOKEN`
`GYG_CURRENCY`	no	Default currency for prices (ISO 4217; falls back to `USD` — the API requires one); per-call `currency` args override
`GYG_LANGUAGE`	no	Default content language (falls back to `en` — the API requires one); per-call `language` args override
`GYG_BASE_URL`	no	API base URL (default `https://api.getyourguide.com/1`)
`GYG_REQUEST_TIMEOUT_MS`	no	Per-request timeout (default 30000)

For local development, put them in a .env next to the server (gitignored; see .env.example).

Behavior notes

Rate limits: one automatic retry on 429/503 honoring Retry-After (capped at 10s). If it still fails, the error tells you to back off.
Timeouts & network failures: a request that exceeds GYG_REQUEST_TIMEOUT_MS, or never reaches the API (DNS, refused, reset), comes back as a tool error naming the request path, with a hint to raise the timeout or check GYG_BASE_URL and your network. Cancelling a call is not wrapped — it stays a cancellation.
Empty arguments: an empty-string query param (e.g. currency: "" or language: "") is dropped rather than sent, so the env default / USD / en fallback applies instead of the API rejecting a blank value.
Auth errors: a 401/403 names both possible causes — a wrong key, or a key whose partner tier doesn't cover that endpoint.
API drift: responses are validated leniently. On an unexpected shape the server logs a precise warning to stderr and returns the raw response rather than breaking. See docs/GETYOURGUIDE-API.md — routes and request shapes are live-verified against the API and its official OpenAPI spec; real 200 bodies still need pinning from a keyed capture.
extraParams: gyg_search_tours and gyg_get_tour_options accept extraParams to pass raw query params the schema doesn't model. A key that collides with one of the tool's own arguments (limit, offset, currency, cnt_language, q, …) is ignored — the typed argument, or its default, always wins. (Before 2.1.6 extraParams overrode them.)
Secrets: upstream error bodies are redacted then truncated before they reach a tool result; the API key is never echoed.

Development

bash

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

Releases are automated with release-please; don't hand-bump versions. PR titles must be conventional commits (feat:, fix:, …) because the repo squash-merges.