Map Traveler MCP
MCP server that lets an AI client move a virtual avatar along Google Maps routes
- Pricing
- Open source
- Platforms
- API, CLI, self-hosted
- Runs
- Locally
- Version
- 0.1.4
- Listing updated
- today
Similar MCP servers
About Map Traveler MCP
Map Traveler MCP is an open-source MCP server for games and play. It runs locally on your machine and is started by your AI client.
The README describes this as an MCP server that sets up a virtual trip for an avatar on Google Maps. A person or an MCP client such as Claude Desktop can set a start point and a destination, then ask the avatar to travel and report progress, with Street View photos that may be composited with an avatar image.
The server exposes tools for reading and setting the traveler's location and destination, starting or stopping a journey, and setting a persona. Journey progress can run in real time or in a skip mode, and a practice mode is offered that does not need API keys. Google Maps keys are needed for real routes and imagery, while image generation, rembg background removal, Turso or local SQLite storage, and Bluesky posting are optional add-ons configured through environment variables.
It suits people experimenting with LLM-driven roleplay, storytelling or game-like interactions over map data, and developers who want an example MCP server with multiple optional backends. The README notes that it is an experimental project, that some features are still being developed, and that paid APIs can incur charges.
Install
Run in a terminal
claude mcp add map-traveler-mcp --env MT_GOOGLE_MAP_KEY='<MT_GOOGLE_MAP_KEY>' --env MT_GEMINI_IMAGE_KEY='<MT_GEMINI_IMAGE_KEY>' --env MT_TURSO_TOKEN='<MT_TURSO_TOKEN>' --env MT_REMBG_WO_KEY='<MT_REMBG_WO_KEY>' --env MT_PIXAI_KEY='<MT_PIXAI_KEY>' --env MT_SD_KEY='<MT_SD_KEY>' --env MT_BS_PASS='<MT_BS_PASS>' -- npx -y @mfukushim/map-traveler-mcpAdd to claude_desktop_config.json
{
"mcpServers": {
"map-traveler-mcp": {
"command": "npx",
"args": [
"-y",
"@mfukushim/map-traveler-mcp"
],
"env": {
"MT_GOOGLE_MAP_KEY": "<MT_GOOGLE_MAP_KEY>",
"MT_GEMINI_IMAGE_KEY": "<MT_GEMINI_IMAGE_KEY>",
"MT_TURSO_TOKEN": "<MT_TURSO_TOKEN>",
"MT_REMBG_WO_KEY": "<MT_REMBG_WO_KEY>",
"MT_PIXAI_KEY": "<MT_PIXAI_KEY>",
"MT_SD_KEY": "<MT_SD_KEY>",
"MT_BS_PASS": "<MT_BS_PASS>"
}
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"map-traveler-mcp": {
"command": "npx",
"args": [
"-y",
"@mfukushim/map-traveler-mcp"
],
"env": {
"MT_GOOGLE_MAP_KEY": "<MT_GOOGLE_MAP_KEY>",
"MT_GEMINI_IMAGE_KEY": "<MT_GEMINI_IMAGE_KEY>",
"MT_TURSO_TOKEN": "<MT_TURSO_TOKEN>",
"MT_REMBG_WO_KEY": "<MT_REMBG_WO_KEY>",
"MT_PIXAI_KEY": "<MT_PIXAI_KEY>",
"MT_SD_KEY": "<MT_SD_KEY>",
"MT_BS_PASS": "<MT_BS_PASS>"
}
}
}
}Add to .vscode/mcp.json
{
"servers": {
"map-traveler-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@mfukushim/map-traveler-mcp"
],
"env": {
"MT_GOOGLE_MAP_KEY": "<MT_GOOGLE_MAP_KEY>",
"MT_GEMINI_IMAGE_KEY": "<MT_GEMINI_IMAGE_KEY>",
"MT_TURSO_TOKEN": "<MT_TURSO_TOKEN>",
"MT_REMBG_WO_KEY": "<MT_REMBG_WO_KEY>",
"MT_PIXAI_KEY": "<MT_PIXAI_KEY>",
"MT_SD_KEY": "<MT_SD_KEY>",
"MT_BS_PASS": "<MT_BS_PASS>"
}
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"map-traveler-mcp": {
"command": "npx",
"args": [
"-y",
"@mfukushim/map-traveler-mcp"
],
"env": {
"MT_GOOGLE_MAP_KEY": "<MT_GOOGLE_MAP_KEY>",
"MT_GEMINI_IMAGE_KEY": "<MT_GEMINI_IMAGE_KEY>",
"MT_TURSO_TOKEN": "<MT_TURSO_TOKEN>",
"MT_REMBG_WO_KEY": "<MT_REMBG_WO_KEY>",
"MT_PIXAI_KEY": "<MT_PIXAI_KEY>",
"MT_SD_KEY": "<MT_SD_KEY>",
"MT_BS_PASS": "<MT_BS_PASS>"
}
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"map-traveler-mcp": {
"command": "npx",
"args": [
"-y",
"@mfukushim/map-traveler-mcp"
],
"env": {
"MT_GOOGLE_MAP_KEY": "<MT_GOOGLE_MAP_KEY>",
"MT_GEMINI_IMAGE_KEY": "<MT_GEMINI_IMAGE_KEY>",
"MT_TURSO_TOKEN": "<MT_TURSO_TOKEN>",
"MT_REMBG_WO_KEY": "<MT_REMBG_WO_KEY>",
"MT_PIXAI_KEY": "<MT_PIXAI_KEY>",
"MT_SD_KEY": "<MT_SD_KEY>",
"MT_BS_PASS": "<MT_BS_PASS>"
}
}
}
}Using several servers? Build one config file with the MCP config generator.
Configuration
MT_GOOGLE_MAP_KEY[Map] Google Map API keyMT_GEMINI_IMAGE_KEY[Image.gemini] Gemini Image Api keyMT_MAX_RETRY_GEMINI[Image.gemini] Number of retries when generating Gemini images Default: 0MT_AVATAR_IMAGE_URI[Image.gemini] 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.MT_MAP_API_URL[Map.etc] Optional: Map API custom endpoint. Example: direction=https://xxxx,places=https://yyyyMT_TIME_SCALE[Map] Optional:Scale of travel time on real roads duration. default 4MT_SQLITE_PATH[db.local] db save path: e.g. %USERPROFILE%/Desktop/traveler.sqlite ,$HOME/traveler.sqliteMT_TURSO_URL[db.api] Turso sqlite API URLMT_TURSO_TOKEN[db.api] Turso sqlite API access tokenMT_REMBG_PATH[rembg.local] absolute path of the installed rembg cliMT_REMBG_URL[rembg.api] withoutbg.com rembg API URLMT_REMBG_WO_KEY[rembg.api] withoutbg.com rembg API keyMT_PIXAI_KEY[Image.pixAi] pixAi API keyMT_SD_KEY[Image.sd] Stability.ai image generation API keyMT_PIXAI_MODEL_ID[Image.pixAi] Optional: pixAi ModelId, if not set use default model 1648918127446573124MT_COMFY_URL[Image.local.ComfyUi] Option: Generate image using ComfyUI API at specified URL. Example: http://192.168.1.100:8188MT_COMFY_WORKFLOW_T2I[Image.local.ComfyUi] Optional: Path to API workflow file when using text to image with ComfyUI. If not specified: assets/comfy/t2i_sample.jsonMT_COMFY_WORKFLOW_I2I[Image.local.ComfyUi] Optional: Path of API workflow file when image to image in ComfyUI. If not specified: assets/comfy/i2i_sample.jsonMT_COMFY_PARAMS[Image.local.ComfyUi] Optional: Variable values to send to the workflow via comfyUI APIMT_FIXED_MODEL_PROMPT[Image] Optional: Fixed avatar generation prompt. You will no longer be able to change your avatar during conversations.MT_BODY_AREA_RATIO[Image] Optional: Acceptable avatar image area ratio. default 0.042MT_BODY_HW_RATIO[Image] Optional: Acceptable avatar image aspect ratios. default 1.5~2.3MT_BODY_WINDOW_RATIO_W[Image] Optional: Avatar composite window horizontal ratio. default 0.5MT_BODY_WINDOW_RATIO_H[Image] Optional: Avatar composite window aspect ratio. default 0.75MT_BS_ID[Sns.Bs] Bluesky sns registration addressMT_BS_PASS[Sns.Bs] bluesky sns passwordMT_BS_HANDLE[Sns.Bs] bluesky sns handle name: e.g. xxxxxxxx.bsky.socialMT_FILTER_TOOLS[etc] Optional: Directly filter the tools to be used. All are available if not specified. e.g. tips,set_traveler_locationMT_MOVE_MODE[etc] Option: Specify whether the movement mode is 'realtime' or 'skip'. default realtimeMT_IMAGE_WIDTH[Image] Option: Output image width (pixels) Default is 512MT_NO_IMAGE[Image] Options: 'true' = do not output image, not specified = output image if possible, default is not specifiedMT_NO_AVATAR[Image] Option: 'true' = Output StreetView image as is without avatar superimposition. Not specified = Superimpose avatar image. Default is not specified.MT_FEED_TAG[Sns] Optional: Specify the feed tag when posting to SNS (#required, 15 characters or more) Default is #geo_less_travelerMT_MAX_SESSIONS[Streamable-http] Maximum number of sessions when using Streamable-httpMT_SESSION_TTL_MS[Streamable-http] Session TTL when using Streamable-httpMT_SERVICE_TTL_MS[Streamable-http] Service TTL when using Streamable-http
Tools this server provides (19)
Taken from the project documentation; the running server may differ.
- get_traveler_view_info
- Gets information about the current travel avatar's location.
- get_traveler_location
- Gets the avatar's address and nearby facilities.
- reach_a_percentage_of_destination
- Moves the avatar a given percentage toward its destination (skip mode only).
- set_traveler_location
- Sets the avatar's current location.
- get_traveler_destination_address
- Gets the avatar's destination address.
- set_traveler_destination_address
- Sets the avatar's destination address.
- start_traveler_journey
- Starts the journey toward the destination (realtime mode only).
- stop_traveler_journey
- Stops the journey (realtime mode only).
- set_traveler_info
- Sets the traveler's name and personality attributes.
- get_traveler_info
- Gets the traveler's attributes.
- set_avatar_prompt
- Sets the prompt used when generating the avatar image.
- reset_avatar_prompt
- Resets the avatar generation prompt to default.
- get_sns_feeds
- Gets Bluesky posts from a custom feed tag.
- get_sns_mentions
- Gets recent likes and replies to the traveler's Bluesky posts.
- post_sns_writer
- Posts a message to Bluesky with the feed tag.
- reply_sns_writer
- Replies to a Bluesky post by ID.
- add_like
- Likes a Bluesky post by ID.
- tips
- Explains how to set up features not yet configured.
- get_setting
- Gets environment and image settings.
What it does
- Virtual avatar travel
- Moves a traveler avatar between addresses or landmarks recognised by Google Maps.
- Street View photo reports
- Fetches nearby Street View imagery and can overlay an avatar on it.
- Optional image generation
- Supports Gemini, PixAI, Stability.ai, or a local ComfyUI server for avatar compositing.
- Journey controls
- Offers real-time or skip movement modes and tools to start, stop, or jump progress.
- Persistent travel log
- Saves progress to a local SQLite file or a Turso libSQL database.
- Bluesky posting
- Can post travel updates and read mentions through an optional Bluesky account.
Good for
- Giving an LLM client a persistent virtual location to roleplay from
- Building a map-based storytelling or game prototype over MCP
- Testing an MCP server with many optional environment-based integrations
- Running a multi-bot travel challenge that reports to a social feed
Pricing
Open source
Free npm package; third-party APIs such as Google Maps and image services may charge.
Map Traveler MCP FAQ
Does it work without API keys?
The README says a practice mode runs without an API key, using only the npx command in the MCP client config.
Which Google APIs are required for full features?
The README lists Street View Static API, Places API (New), Time Zone API and Directions API.
Can it run as a remote server?
Yes, the README describes Streamable-HTTP support with per-session configuration, and a Smithery listing.
Is Map Traveler MCP free?
Yes. Map Traveler MCP is open source, so you can use and self-host it for free.
How do I add Map Traveler MCP to Claude Code?
Run this command in your terminal: claude mcp add map-traveler-mcp --env MT_GOOGLE_MAP_KEY='<MT_GOOGLE_MAP_KEY>' --env MT_GEMINI_IMAGE_KEY='<MT_GEMINI_IMAGE_KEY>' --env MT_TURSO_TOKEN='<MT_TURSO_TOKEN>' --env MT_REMBG_WO_KEY='<MT_REMBG_WO_KEY>' --env MT_PIXAI_KEY='<MT_PIXAI_KEY>' --env MT_SD_KEY='<MT_SD_KEY>' --env MT_BS_PASS='<MT_BS_PASS>' -- npx -y @mfukushim/map-traveler-mcp
Where this comes from
- Description: written from the project's README and its MCP Registry entry.
- Install steps: from the official MCP Registry entry.