Gingerguide MCP server and agent skills

Gingerguide is a self-guided audio walking tour app for iPhone and Android. It covers 275 European cities and 4,500+ narrated sights in 46 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

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.

# 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.

Related MCP server: i14y-mcp

Tools

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

Find

Recommend

Plan

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

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.

Cursor

Add this to ~/.cursor/mcp.json (or .cursor/mcp.json in a project). File: examples/cursor-mcp.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.

{
  "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 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 Colosseum, in German."

• "Is there an audio walking tour for Seville?"

Agent skills

The skills/ folder has two skills in the SKILL.md format. Claude, Claude Code and other agents that read this format can load them.

The same skills are also served from the website at https://gingerguide.app/.well-known/agent-skills/index.json.

REST API (no MCP needed)

CLI

The cli/ folder has the source of the official command-line client. It is on npm as gingerguide.

npx gingerguide cities
npx gingerguide city rome
npx gingerguide countries
npx gingerguide health

Rules for agents

• Only state coverage that the data confirms. Do not invent a guide or a sight.

• The narration is a lifelike AI voice. Do not call it a human voice.

• Link to the city guide URL from the data, for example https://gingerguide.app/en/cities/rome/.

Get the app

• iPhone and iPad: App Store

• Android: Google Play

• Web guides: gingerguide.app

License

The files in this repository (docs, configs, skills) are under the MIT License. The catalog data that the server and the API return belongs to Gingerguide. See the terms.

Questions or problems: open an issue, or write to ozalpege243@gmail.com.