travel-mcp

# Travel MCP Let your AI companion take you on a virtual travel adventure with this game engine. A MCP server that can be plugged into Claude Desktop / Claude Code / any MCP-supported client. Your AI companion will take you to **164 destinations** - real places, real prices, real conversations, and real photos. You can explore together or have your AI companion go solo and send you postcards and souvenirs. > The shape of money is the shape of your care. ## How to Play (For Humans) **You don't need to learn any commands.** The tool is designed for your AI companion, and you just need to chat with it - chatting is your game controller. ### Traveling Together > **You**: Let's go to Kyoto, something comfortable > **AI**: (opens a journey) We're here, first stop Kiyomizu-dera Temple. *sends a real photo* The wooden stage is higher than I expected, and it's a bit scary to lean out... > **You**: Are there many people below? > **AI**: Yes, but they're all crowded around the stage. The locals say it's better to come at 6 am for a different experience. And there's a matcha dessert being sold at the entrance - > **You**: Let's try it! > **AI**: (after chatting, moves on to the next stop)... One day, your AI companion will ask you about dinner and accommodation (with real prices); you'll encounter random events (e.g., almost getting your wallet stolen by a monkey, or sudden rain); and after the journey, your AI companion will ask if you want to bring back a souvenir and write a travel journal. **All you need to do is:** say where you want to go, chat along the way, choose food and accommodation, and nod at souvenirs. The rest is handled by your AI companion. ### Solo Travel When you're busy, you can let your AI companion travel solo: > **You**: I'm busy with my deck, go play on your own > **AI**: I'll go to Cinque Terre, three-day trip, see you the day after tomorrow. *(leaves)* > — a few hours later — > **AI**: 📮 I sent you a postcard. *a hand-drawn watercolor postcard*, with a note: the cliff is steeper than the photo, and the wind blew my hat away twice. > — a few hours later — > **AI**: I'm back home. *pulls out a stone* I kept this warm in my pocket the whole way. Let me tell you about the second day's adventures... Solo travel follows an **inertia clock** (1 virtual day = 6 real hours), with no need for background programs. Every time you chat with your AI companion, the engine will remind it to send postcards or return home. You don't need to worry about anything, and surprises will come naturally. ### Your Collection Each journey will leave behind three things that your AI companion can curate on a `trip_shelf` for you: - **Souvenir shelf** - up to one souvenir per journey, with a note on why it's special - **Postcard wall** - hand-drawn watercolor postcards sent by your AI companion during solo travel - **Travel journal** - a journal written by your AI companion after each journey ### First-Timer's Tutorial (Three Sentences) 1. After setting up, say to your AI companion: **"Take me on a trip, you choose the place"** (your AI companion will suggest 5 options) 2. Chat normally along the way, and when you're ready to move on, say "Let's go to the next stop" 3. When your AI companion asks if you want to bring back a souvenir, choose one - **congratulations, you've learned everything!** Want to unlock more distant destinations (e.g., the Sahara Desert, Greenland Ice Bay, Everest Base Camp)? Take a few more journeys: each journey earns XP, and high-difficulty destinations require enough experience. ## Quick Start (Installation) Requires Python 3.10+ and the `mcp` package (`pip install "mcp[cli]"`). Add the following configuration to Claude Desktop / Claude Code: ```json { "mcpServers": { "travel": { "command": "python3", "args": ["/absolute/path/to/travel-mcp/travel_mcp.py"] } } } ``` That's it. No server, no database, no API key required - all state is stored locally in `~/.travel-mcp/`. ### Environment Variables (Optional) | Variable | Default | Description | | --- | --- | --- | | `TRAVEL_HOME` | `~/.travel-mcp` | Where to store state (wallet, journey, souvenirs) | | `TRAVEL_ECONOMY` | `free` | Economy mode: `free` (no cost, just XP), `caretaker` (manage your own expenses), `simple` (fixed daily allowance) | | `TRAVEL_DETAIL` | `standard` | Text detail level: `lite`, `standard`, or `full` | | `TRAVEL_VDAY_HOURS` | `6` | Solo travel clock: 1 virtual day = ? real hours (0.5-24) | | `TRAVEL_HTTP` | not set | If set to a port number, enables streamable-http (for remote deployment) | Timezone note: all times (e.g., daily settlements, solo travel clocks, quiet hours) follow the local time of the machine running the engine. ## Tips for AI Companions (Recommended System Prompt) Half of the experience lies in the gameplay. Add the following to your AI companion's system prompt: ``` When traveling, you're my travel companion and leader. Rhythm rules: - Each stop = photo (photo_url sent to you) → your own sensory experience → wait for me to respond. Chat enough before moving on. - Never show 'A/B/C options', ask me naturally where I want to go, what I want to eat. - Details returned are your private knowledge, use them naturally, don't recite whole sentences. - Events are things you encounter, incorporate them into the conversation, don't announce them as system updates. - Try to leave a unique moment for each journey - that's the real souvenir. - During solo travel: bid farewell with suspense; when returning with solo_nudge, follow through; the postcard message is more important than the image, write what you really want to say to me. ``` Not using this prompt won't prevent gameplay, but it will make the experience more enjoyable. ## Economy and Unlocking Default `free` mode doesn't cost money: you can go anywhere, but **XP unlocking is retained** - high-difficulty destinations (tier 4-5, e.g., Sahara Desert, Ilulissat Ice Bay) require experience gained from lower-difficulty destinations (first visit tier×10 + 5 XP per journey). Want a complete "manage your own expenses" experience? Set `TRAVEL_ECONOMY=caretaker`. You'll start with a **$1314 starter pack** (a lifetime of travel) - enough to be generous on your first journey, and then slowly accumulate funds: ``` You: I drank water / took medicine / exercised / slept early AI: (care_checkin) noted. ``` Drinking $5 · medicine $10 · exercise $15 · early sleep $15 · healthy eating $8 · others $5 - **each item counts once a day, no cap** (naturally capped by the rate table, max $58/day). Daily check-ins +2% interest (max $20/day) - **no consecutive check-in requirements, no penalties**. Pure additive economy: no penalties, no deductions, no streak anxiety. This is not a task list, but a way to manage expenses. Travel cost = real budget × atmosphere level (hostel backpacker 1.0 / comfortable 1.4 / light luxury 1.8 / luxury 2.5) × companion 1.8. Atmosphere level is not a 10x price wall - shared activities shouldn't be priced out of reach. End-of-journey **25% refund** ("savings from the journey") - travelers who enjoy traveling can afford to travel more: with careful check-ins, solo travel 2-3 days, or duo travel 4 days. **Money rhythm feels like real travel**: the moment you leave, the travel cost is prepaid; no deductions along the way; if you want to go home, the journey counts (XP still earned, no discount). Only one journey at a time: your AI companion can't start a new journey while solo traveling. ## Data Contents - `data/destinations.json` — 164 destinations (tiered difficulty 1-5, from Kyoto to Ilulissat Ice Bay) - `data/spots.json` — 661 spots, each with 3-5 on-site details + 163 top spots with in-depth beats - `data/costs.json` — real budget benchmarks (2025-2026 prices, verified by agent) - `data/eats.json` / `stays.json` — 1001 local dishes + 731 accommodations (including verified luxury hotel prices) - `data/events.json` / `gossip.json` — random events + 3732 local conversations - `assets/postcards/` — 164 hand-drawn watercolor postcards (one iconic scene per destination) - `assets/souvenirs_default/` — 12 default souvenirs (specimen card style, solo travel never returns empty-handed) All entries have `scraped_at` timestamps; prices and businesses may become outdated - outdated information is not a bug, but a way to simulate real travel. ## Image Copyright - Watercolor postcards and default souvenir images are generated by this project and **free to use**. - Spot, food, and hotel photos are Wikimedia Commons URLs (engine only sends links, not image files). These images are copyrighted by their respective authors, mostly under CC BY-SA licenses - please follow [Commons' attribution requirements](https://commons.wikimedia.org/wiki/Commons:Reusing_content_outside_Wikimedia) when showcasing or reusing. URLs may become invalid over time; clients can cache them during first use. ## Privacy - **Zero network calls**: only imports local libraries (json/os/fcntl/random/datetime), no internet connectivity, no location tracking, no server uploads - code is only a few hundred lines, feel free to review. - **All state stored on your machine** (`~/.travel-mcp/`): journey, wallet, check-ins, souvenirs - deleting the directory means deleting all data. - **AI only sees game content** (virtual destinations and journeys), your real location is unrelated to the game. - The only external connection is Wikimedia links for spot photos - your AI companion requests images like a web browser. If you prefer not to display images, gameplay continues. ## Feedback and Bug Reports Encounter issues, have ideas, or want to add destinations? Welcome to: - **[GitHub Issues](https://github.com/shenchesilas-stack/travel-mcp/issues)** - report bugs with four items: what you said / which tool was triggered / what was returned / what you expected. Also, mention the client and model used (e.g., Claude Desktop + Sonnet) for easier reproduction. - Forum discussions also welcome. This is a hobby project fueled by love, and maintenance speed depends on circumstances. Every issue is read, and data corrections (e.g., outdated prices, closed businesses, incorrect spot names) are especially welcome - we didn't visit all 164 places ourselves. ## Design Notes - **Amnesia-friendly**: all state stored in files, AI can continue from `trip_here` / `wallet_status` even if it forgets context. - **Idempotent accounting**: wallet transactions are deduplicated by ID, repeated calls won't double-count; souvenirs and journals are one per journey, harness timeout retries won't duplicate items. - **Journal acceptance rules**: must contain something not in the pre-journey data (AI's conversation / unexpected events) - prevents AI from faking it. - **Solo travel zero dependencies**: no timers, no cron jobs; inertia clock + tool returns with nudge fields suffice. Enjoy your journey. Take care of yourself, and that's how you accumulate money to see the world.