map-traveler

Virtual traveler library for MCP

Installation

Run this command in your terminal to add the MCP server to Claude Code.

Run in terminal:

Command

claude mcp add --transport stdio mfukushim-map-traveler-mcp npx -y @mfukushim/map-traveler-mcp \
  --env MT_SD_KEY="(or Stability.ai image generation API key" \
  --env MT_COMFY_URL="(Option: Generate image using ComfyUI API at specified URL. Example: http://192.168.1.100:8188)" \
  --env MT_PIXAI_KEY="(pixAi API key)" \
  --env MT_REMBG_URL="(rembg API URL)" \
  --env MT_TURSO_URL="(Turso sqlite API URL)" \
  --env MT_REMBG_PATH="(absolute path of the installed rembg cli)" \
  --env MT_TIME_SCALE="(Optional:Scale of travel time on real roads duration. default 4)" \
  --env MT_MAP_API_URL="(Optional: Map API custom endpoint. Example: direction=https://xxxx,places=https://yyyy )" \
  --env MT_SQLITE_PATH="(db save path: e.g. %USERPROFILE%/Desktop/traveler.sqlite ,$HOME/traveler.sqlite )" \
  --env MT_TURSO_TOKEN="(Turso sqlite API access token)" \
  --env MT_REMBG_WO_KEY="(withoutbg.com rembg API key)" \
  --env MT_GOOGLE_MAP_KEY="(Google Map API key)" \
  --env MT_PIXAI_MODEL_ID="(Optional: pixAi ModelId, if not set use default model 1648918127446573124 " \
  --env MT_AVATAR_IMAGE_URI="(Character reference image uri (file:// or https://) when generating Gemini image. Multiple settings can be made by separating them with the '|'. When multiple settings are made, they will be selected randomly.)" \
  --env MT_GEMINI_IMAGE_KEY="(Gemini Image Api key)" \
  --env MT_MAX_RETRY_GEMINI="(Number of retries when generating Gemini images Default: 0)" \
  --env MT_COMFY_WORKFLOW_T2I="(Optional: Path to API workflow file when using text to image with ComfyUI. If not specified: assets/comfy/t2i"

How to use

This MCP server, map-traveler, creates a virtual traveling environment for an avatar that moves through Google Maps. You can interact with the traveling avatar from an MCP client (for example Claude Desktop) by sending instructions like where to go, requesting current location, or prompting the generation of travel images. The server exposes a set of MCP functions to query the traveler’s status, set locations and destinations, start or stop journeys, and manage avatar prompts and SNS interactions. It also supports both stdio-style and Streamable-HTTP configurations, making it compatible with multiple client setups. When using it, configure the required API keys and image generation settings in the environment variables, then run the MCP server via the npm/npx workflow and issue commands like get_traveler_view_info, set_traveler_location, start_traveler_journey, or get_traveler_destination_address to guide the avatar’s journey and retrieve progress and imagery.

How to install

Prerequisites

Node.js (recommended LTS) and npm installed on your system
Access keys for Google Maps API and image generation services (Gemini, rembg, etc.)
Optional: a SQLite or Turso backend if you plan to persist traveler state

Step-by-step installation

Install the MCP server package (via npx or npm) from the npm registry:
- Using npx (recommended for quick start): npx -y @mfukushim/map-traveler-mcp
- Or install locally and run (optional): npm install -g @mfukushim/map-traveler-mcp map-traveler-mcp
Prepare environment variables (example placeholders): MT_GOOGLE_MAP_KEY=YOUR_GOOGLE_MAPS_KEY MT_GEMINI_IMAGE_KEY=YOUR_GEMINI_IMAGE_KEY MT_MAX_RETRY_GEMINI=0 MT_AVATAR_IMAGE_URI=(image URI or patterns) MT_MAP_API_URL=(optional map API endpoint overrides) MT_TIME_SCALE=4 MT_SQLITE_PATH=$HOME/traveler.sqlite MT_TURSO_URL=YOUR_TURSO_URL MT_TURSO_TOKEN=YOUR_TURSO_TOKEN MT_REMBG_PATH=/usr/local/bin/rembg MT_REMBG_URL=(optional rembg API URL) MT_REMBG_WO_KEY=YOUR_REMGB_API_KEY MT_PIXAI_KEY=YOUR_PIXAI_KEY MT_SD_KEY=YOUR_STABILITY_AI_KEY MT_PIXAI_MODEL_ID=(optional model id) MT_COMFY_URL=(optional comfyUI URL) MT_COMFY_WORKFLOW_T2I=(optional path to t2i workflow)
Start the server with the configured environment:

npx -y @mfukushim/map-traveler-mcp or, if installed globally: map-traveler-mcp
Connect from an MCP client (e.g., Claude Desktop) and begin issuing commands such as get_traveler_view_info, set_traveler_location, and start_traveler_journey to simulate and visualize the avatar's journey.

Additional notes

Tips and considerations:

The server supports both stdio and Streamable-HTTP interfaces; choose the configuration that matches your client setup.
Ensure your Google Maps API key has appropriate permissions (Places, Maps, Street View as needed).
Image generation may rely on Gemini, pixAi, or rembg services; provide valid keys and monitor quotas.
For persistence, MT_SQLITE_PATH can point to a local sqlite file; consider Turso if you prefer a cloud-backed API.
If you encounter image generation delays, adjust MT_MAX_RETRY_GEMINI and MT_TIME_SCALE to tune performance and retry behavior.
The CLI and prompts can be customized via set_avatar_prompt and reset_avatar_prompt to change avatar visuals across runs.

Related MCP Servers

context7

47.3k

Context7 MCP Server -- Up-to-date code documentation for LLMs and AI code editors

obsidian -tools

612

Add Obsidian integrations like semantic search and custom Templater prompts to Claude or any MCP client.

MiniMax -JS

105

Official MiniMax Model Context Protocol (MCP) JavaScript implementation that provides seamless integration with MiniMax's powerful AI capabilities including image generation, video generation, text-to-speech, and voice cloning APIs.

mcp-bundler

Is the MCP configuration too complicated? You can easily share your own simplified setup!

akyn-sdk

Turn any data source into an MCP server in 5 minutes. Build AI-agents-ready knowledge bases.

promptboard

The Shared Whiteboard for Your AI Agents via MCP. Paste screenshots, mark them up, and share with AI.