gingerguide

# Gingerguide MCP server and agent skills

**[Gingerguide](https://gingerguide.app) is a self-guided audio walking tour app for iPhone and Android.** It covers 169 European cities and 3,100+ narrated sights in 39 countries. Each sight has a researched 2 to 3 minute story, read by a lifelike AI voice, in English, Spanish, French, German, Turkish and Chinese. Cities work fully offline.

This repository lets AI assistants and agents use the Gingerguide catalog. It contains:

- The connection details for the public **Gingerguide MCP server** at `https://gingerguide.app/mcp`. Its 14 tools find sights by interest, historical period or location, recommend sights and cities, compare cities, find day trips, give practical visit facts, and plan walking tours and multi-day itineraries, in six languages.
- Two **agent skills** (`SKILL.md` format) for audio tour lookup and one-day city walks.
- Ready-to-copy **client configs** and **curl examples**.

The server is read-only. It needs no API key and no sign-in. An optional free API key raises the daily limit (see [Optional free API key](#optional-free-api-key)).

| | |
|---|---|
| MCP endpoint | `https://gingerguide.app/mcp` |
| Transport | Streamable HTTP (stateless, JSON responses) |
| Auth | None required (optional free API key) |
| MCP Registry name | `app.gingerguide/catalog` |
| Developer docs | <https://gingerguide.app/developers/> |
| OpenAPI (REST) | <https://gingerguide.app/api/openapi.json> |
| llms.txt | <https://gingerguide.app/llms.txt> |

## Optional free API key

The server works without a key. Without a key, it allows 1,000 tool calls per IP address per UTC day. Hosted assistants such as Claude and ChatGPT call from a few shared IP addresses, so their requests get 50,000 per IP address per day. A free key raises the limit to 20,000 tool calls per key per day and shows your usage. It is useful when your agent runs on a shared cloud (Vercel, AWS, Cloudflare). Only `tools/call` counts. There is no sign-up and no email.

```bash
# Create a key (it is shown once; the server stores only its hash)
curl -sS -X POST https://gingerguide.app/api/keys \
  -H 'content-type: application/json' -d '{"label":"my-agent"}'

# Use it
curl -sS https://gingerguide.app/mcp \
  -H 'authorization: Bearer ggk_...' \
  -H 'content-type: application/json' -H 'accept: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Usage for the last 30 days, and revoke
curl -sS https://gingerguide.app/api/keys/me -H 'authorization: Bearer ggk_...'
curl -sS -X DELETE https://gingerguide.app/api/keys/me -H 'authorization: Bearer ggk_...'
```

You can also send the key as `X-API-Key`. An unknown or revoked key gets HTTP 401. Remove the header to continue without a key. Tool-call responses carry `RateLimit` and `X-RateLimit-Remaining` headers. Details: <https://gingerguide.app/developers/#api-key>.

## Tools

Every tool is read-only (`readOnlyHint: true`) and accepts `language`: `en`, `es`, `fr`, `de`, `tr` or `zh`.

### Find

| Tool | What it does | Main arguments |
|---|---|---|
| `search_attractions` | Searches sights in all cities or in one city, by free text, category, interest, historical period, indoor or outdoor, visit length, free entry, or distance from a point. Example: five Byzantine sights in Istanbul. | `query`, `city_id`, `country`, `categories`, `interests`, `periods`, `setting`, `free_only`, `near_lat`, `near_lng`, `radius_km`, `sort`, `limit` |
| `find_nearby_attractions` | Returns the sights closest to a latitude and longitude, with walking minutes. If no sight is in the radius, it returns the nearest covered city. | `lat`, `lng`, `radius_km`, `interests`, `categories`, `pace` |
| `get_attraction` | Returns one sight: long description, a notable fact, photo, coordinates, map link, visit time and the nearest other sights. In researched cities it adds entry, booking, weekly closing days, dress code and the official site. | `attraction_id` (for example `rome-colosseum`) |
| `get_visit_info` | Practical facts for one city: best months and crowd seasons, how to get from the airport, main station or cruise port to the centre, city passes, free sights, what to book ahead, weekly closing days and dress codes. Every fact has a source and a check date. Researched cities only (Rome, Barcelona and Vienna so far); for other cities it says so. | `city_id`, `topics` |
| `search_cities` | Finds cities by name (in any of the six languages), country or region. Returns the city id that the other tools need. | `query`, `country`, `limit` |
| `get_city_guide` | Returns one city: overview, headline sights, lesser-known sights, and every sight with category, coordinates and visit time. `detail: "full"` adds every long description. | `city_id`, `detail` |
| `list_countries` | Lists the covered countries with their city ids. | none |
| `get_catalog_overview` | Returns coverage totals, languages, and the exact values that the `categories`, `interests` and `periods` filters accept. | none |

### Recommend

| Tool | What it does | Main arguments |
|---|---|---|
| `recommend_attractions` | Picks sights in one city for the traveler's interests, favourite periods, headline sights or hidden gems, indoor or outdoor, and time available. Each pick says why it was chosen. | `city_id`, `interests`, `periods`, `style`, `setting`, `available_minutes`, `exclude_ids` |
| `recommend_destinations` | Ranks cities for interests or historical periods, for example "best cities for Byzantine history", and says why. | `interests`, `periods`, `country`, `trip_days` |
| `compare_cities` | Compares two to four cities side by side: sights, days needed, strongest interests and periods, share of indoor sights, headline sights and the distance between them. Says which city is stronger for each interest or period. | `city_ids`, `interests`, `periods`, `trip_days` |
| `find_day_trips` | Lists covered cities that make a day trip from a base city, ranked by distance, interests and fame, with what to see there in one day. Sea crossings that need a flight are left out; short ferry trips are marked. | `city_id`, `max_distance_km`, `interests`, `periods`, `hours_on_site` |

### Plan

| Tool | What it does | Main arguments |
|---|---|---|
| `plan_walking_tour` | Builds an ordered walking route in one city for a time budget. Returns each stop with walking minutes, time on site, clock times, and a Google Maps walking link. | `city_id`, `duration_minutes`, `interests`, `periods`, `style`, `pace`, `start_lat`, `start_lng` or `start_attraction_id`, `start_time`, `must_include`, `weekday` |
| `plan_trip_itinerary` | Plans 1 to 7 days in one city. Each day covers one or two walkable areas, with a public transport hop between them. | `city_id`, `days`, `hours_per_day`, `interests`, `periods`, `style`, `pace`, `start_time`, `start_weekday` |

**Filter values.** Interests: `history`, `architecture`, `art`, `museums`, `religious_sites`, `archaeology`, `nature`, `views`, `food`, `local_life`, `shopping`, `relaxing`, `royalty`, `military`, `music`, `literature`, `science`, `performing_arts`, `memorials`. Periods: `prehistoric`, `ancient_greek`, `etruscan`, `roman`, `byzantine`, `medieval`, `gothic`, `moorish_islamic`, `ottoman`, `renaissance`, `baroque`, `georgian_neoclassical`, `nineteenth_century`, `art_nouveau`, `twentieth_century_modern`, `world_war_ii`, `cold_war`. Style: `must_see`, `balanced`, `hidden_gems`. Pace: `relaxed`, `normal`, `brisk`.

**Limits of the data.** Interests, periods and indoor or outdoor are derived from each sight's category and description. Walking times are estimates (straight-line distance x 1.3 at the chosen pace). Day-trip and comparison distances are straight-line and come without travel times. With `weekday`, the planners leave out sights that are closed that day or temporarily closed, in researched cities. Opening hours and ticket prices are not included. Bad input returns an error that names the allowed values.

## Connect a client

### Claude Code

```bash
claude mcp add --transport http gingerguide https://gingerguide.app/mcp
```

### Claude (desktop and web)

Open **Settings → Connectors → Add custom connector**. Set the name to `Gingerguide` and the URL to `https://gingerguide.app/mcp`.

For older Claude Desktop builds that only read `claude_desktop_config.json`, use the bridge config in [`examples/claude_desktop_config.json`](examples/claude_desktop_config.json).

### Cursor

Add this to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project). File: [`examples/cursor-mcp.json`](examples/cursor-mcp.json).

```json
{
  "mcpServers": {
    "gingerguide": { "url": "https://gingerguide.app/mcp" }
  }
}
```

### VS Code (GitHub Copilot agent mode)

Add this to `.vscode/mcp.json`. File: [`examples/vscode-mcp.json`](examples/vscode-mcp.json).

```json
{
  "servers": {
    "gingerguide": { "type": "http", "url": "https://gingerguide.app/mcp" }
  }
}
```

### ChatGPT

In a workspace or plan that allows custom connectors (developer mode), add a new connector with the URL `https://gingerguide.app/mcp` and no authentication.

### Any other client

Any MCP client that supports remote Streamable HTTP servers can connect to `https://gingerguide.app/mcp`. See [`examples/curl.md`](examples/curl.md) for raw JSON-RPC calls.

## Example prompts

- "Find five Byzantine historical sights in Istanbul."
- "Plan a two-hour historical walking tour of Rome starting at 10:00."
- "I'm staying near St. Stephen's Cathedral in Vienna. What can I walk to in 10 minutes?"
- "Plan three days in Vienna for art and music lovers."
- "Which European cities are best for Byzantine history?"
- "What are good day trips from Florence?"
- "How do I get from the Civitavecchia cruise port to Rome, and what do I need to book?"
- "Plan four hours of art in Rome on a Sunday."
- "Porto or Lisbon for a first trip? Compare them."
- "Show me hidden gems in Paris for architecture lovers, indoors because it is raining."
- "Tell me about the Colos