Gingerguide MCP server and agent skills
Gingerguide is a self-guided audio walking tour app for iPhone and Android. It covers 166 European cities and 3,000+ narrated sights in 36 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.
- 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.
| Tool | What it does | Arguments |
|---|
search_cities | Finds cities by name or country. Returns the number of sights and the web guide URL for each city. | query, country, limit (all optional) |
get_city_guide | Returns one city with all its narrated sights: name, one-line description, category, coordinates and visit time in minutes. | city_id (for example rome) |
list_countries | Lists the covered countries and the number of cities in each. | none |
get_catalog_overview | Returns catalog totals, supported languages and app download links. | none |
All tools are marked readOnlyHint: true.
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
- "Is there an audio walking tour for Seville?"
- "Plan a one-day walk in Florence with the Gingerguide sights, in walking order."
- "Which Gingerguide cities are in Portugal?"
- "How many cities and languages does Gingerguide cover?"
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)
| Endpoint | Returns |
|---|
GET https://gingerguide.app/api/cities.json | All cities with id, country, sight count and guide URL |
GET https://gingerguide.app/api/cities/{id}.json | One city with all its sights |
GET https://gingerguide.app/api/openapi.json | The OpenAPI description |
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
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.