Build GPS-based interactive adventures with plain English. wheriflo is an MCP server and CLI that lets AI create, test, and compile Wherigo geocaching cartridges for you.
What is Wherigo? — A GPS-based interactive game. Players walk to real-world locations with their phone, and the app tells a story, asks questions, and reveals secrets as they explore. Think of it as a location-based choose-your-own-adventure.
You don't need to write code. Just describe what you want.
Tell the AI what kind of adventure you want—a mystery, a history walk, a scavenger hunt. Give it GPS coordinates from Google Maps.
→The AI scaffolds the project, writes all the Lua code, lints for mistakes, and compiles it—automatically.
→Test in the browser, then ask for changes. “Make the puzzle harder.” “Add a hint at stop 3.” The AI rebuilds and retests after every tweak.
→Upload the finished cartridge to wherigo.com, open the Wherigo app on your phone, and walk the real-world route.
Works with any MCP client
From scaffolding to publishing—wheriflo handles the entire creation workflow.
One command creates a complete cartridge project with a starter Lua template, all required metadata fields, and GPS coordinates ready to customize.
Catches Wherigo-specific mistakes that crash players—like iOS-breaking nil assignments, wrong enums, and Groundspeak compiler bugs—before you build.
Build locally to .gwc/.gwz for instant testing, or validate through the official Groundspeak compiler API to guarantee compatibility with all Wherigo players.
A built-in web player lets you (and the AI) walk through every zone, message, and choice in your browser. Auto-reloads on file changes.
A secure Lua 5.1 runtime with the Wherigo API shimmed in. Dangerous modules (io, os, debug) are removed. Safe for AI-driven play-testing.
Embed JPG, PNG, GIF, BMP images and MP3, WAV, OGG audio. The packager discovers media declarations and bundles them into the cartridge automatically.
API reference, design guide, and starter template are available as MCP resources. The AI reads them automatically to write correct code.
When you're ready, wheriflo opens wherigo.com and copies the file path to your clipboard. Tracks your cartridge GUID for seamless updates.
Wherigo.com credentials stored in your OS keyring (Windows Credential Manager, macOS Keychain, Linux Secret Service). Never logged or exposed.
The AI uses these tools behind the scenes. You just talk in plain English.
wheriflo_init Scaffold projectwheriflo_build Compile locallywheriflo_compile Groundspeak APIwheriflo_lint Check for mistakeswheriflo_play Start web playerwheriflo_teleport Enter a zonewheriflo_leave_zone Exit a zonewheriflo_set_position Set GPS coordswheriflo_respond Answer promptswheriflo_autoplay Batch play-testwheriflo_get_state Inspect game statewheriflo_get_resource Read docswheriflo_validate Validate .gwcwheriflo_publish Upload to wherigo.comwheriflo_reset Full state wipewheriflo_stop Stop web playerapi-reference
design-guide
lua-template
design-cartridge
review-cartridge
Every MCP tool is also available as a CLI command. No AI editor required.
The AI handles every step automatically. You just describe what you want.
"Create a mystery about the history of Pioneer Square with 5 stops"
Right-click any location on Google Maps to copy coordinates
Creates the directory, starter file, and all required metadata
Zones, messages, items, puzzles, branching storylines—all generated
Catches iOS crashes, compiler bugs, and Wherigo-specific pitfalls
Produces the .gwc file and validates with the Groundspeak compiler
Enters every zone, answers every question, verifies the ending
You get a finished .gwc file to publish on wherigo.com and play on your phone
Install Python and uv, add one config snippet, and you're ready to go.
Create .vscode/mcp.json in your project:
{
"servers": {
"wherigo": {
"command": "uvx",
"args": ["wheriflo", "mcp"]
}
}
}
Restart VS Code, open Copilot Chat, and ask it to create a Wherigo cartridge.
Add to claude_desktop_config.json:
{
"mcpServers": {
"wherigo": {
"command": "uvx",
"args": ["wheriflo", "mcp"]
}
}
}
On Windows, use "command": "cmd" and "args": ["/c", "uvx", "wheriflo", "mcp"].
Run one command:
claude mcp add wherigo -- uvx wheriflo mcp
Run one command:
codex mcp add -- uvx wheriflo mcp
Add to Cursor Settings → MCP Servers:
{
"mcpServers": {
"wherigo": {
"command": "uvx",
"args": ["wheriflo", "mcp"]
}
}
}
Install permanently instead of using uvx:
pip install wheriflo
Then replace "command": "uvx", "args": ["wheriflo", "mcp"] with
"command": "wheriflo", "args": ["mcp"] in any config above.
After setup, open your AI chat and paste this prompt. Replace the location with somewhere near you.
Create a Wherigo cartridge about the history of Pioneer Square
in Seattle. Start at Smith Tower (47.6019, -122.3317) and
include 4 stops within walking distance. Make it a mystery
with multiple choice questions at each stop.
The AI will scaffold the project, write the story, lint it, build it, play-test every path, and give you a finished
.gwc file ready to upload.
Open source. Free to use. Works with any MCP-compatible AI assistant.