Skip to content
MCP server

Map Traveler MCP

MCP server that lets an AI client move a virtual avatar along Google Maps routes

Runs locallyStatus and history
Install
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-mcp

Add 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 key
  • MT_GEMINI_IMAGE_KEY[Image.gemini] Gemini Image Api key
  • MT_MAX_RETRY_GEMINI[Image.gemini] Number of retries when generating Gemini images Default: 0
  • MT_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://yyyy
  • MT_TIME_SCALE[Map] Optional:Scale of travel time on real roads duration. default 4
  • MT_SQLITE_PATH[db.local] db save path: e.g. %USERPROFILE%/Desktop/traveler.sqlite ,$HOME/traveler.sqlite
  • MT_TURSO_URL[db.api] Turso sqlite API URL
  • MT_TURSO_TOKEN[db.api] Turso sqlite API access token
  • MT_REMBG_PATH[rembg.local] absolute path of the installed rembg cli
  • MT_REMBG_URL[rembg.api] withoutbg.com rembg API URL
  • MT_REMBG_WO_KEY[rembg.api] withoutbg.com rembg API key
  • MT_PIXAI_KEY[Image.pixAi] pixAi API key
  • MT_SD_KEY[Image.sd] Stability.ai image generation API key
  • MT_PIXAI_MODEL_ID[Image.pixAi] Optional: pixAi ModelId, if not set use default model 1648918127446573124
  • MT_COMFY_URL[Image.local.ComfyUi] Option: Generate image using ComfyUI API at specified URL. Example: http://192.168.1.100:8188
  • MT_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.json
  • MT_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.json
  • MT_COMFY_PARAMS[Image.local.ComfyUi] Optional: Variable values to send to the workflow via comfyUI API
  • MT_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.042
  • MT_BODY_HW_RATIO[Image] Optional: Acceptable avatar image aspect ratios. default 1.5~2.3
  • MT_BODY_WINDOW_RATIO_W[Image] Optional: Avatar composite window horizontal ratio. default 0.5
  • MT_BODY_WINDOW_RATIO_H[Image] Optional: Avatar composite window aspect ratio. default 0.75
  • MT_BS_ID[Sns.Bs] Bluesky sns registration address
  • MT_BS_PASS[Sns.Bs] bluesky sns password
  • MT_BS_HANDLE[Sns.Bs] bluesky sns handle name: e.g. xxxxxxxx.bsky.social
  • MT_FILTER_TOOLS[etc] Optional: Directly filter the tools to be used. All are available if not specified. e.g. tips,set_traveler_location
  • MT_MOVE_MODE[etc] Option: Specify whether the movement mode is 'realtime' or 'skip'. default realtime
  • MT_IMAGE_WIDTH[Image] Option: Output image width (pixels) Default is 512
  • MT_NO_IMAGE[Image] Options: 'true' = do not output image, not specified = output image if possible, default is not specified
  • MT_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_traveler
  • MT_MAX_SESSIONS[Streamable-http] Maximum number of sessions when using Streamable-http
  • MT_SESSION_TTL_MS[Streamable-http] Session TTL when using Streamable-http
  • MT_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.

How AIPoweredBot checks servers