# Map Traveler MCP

> Map Traveler MCP is an open-source MCP server for games and play. MCP server that lets an AI client move a virtual avatar along Google Maps routes. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** API, CLI, self-hosted
- **Repository:** https://github.com/mfukushim/map-traveler-mcp
- **MCP Registry name:** io.github.mfukushim/map-traveler-mcp
- **Categories:** [games and play](https://ai-powered.com/categories/games-and-play)
- **Listing updated:** 2026-11-18

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

```sh
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
```

### Claude Desktop (claude_desktop_config.json)

```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>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```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>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```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>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```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>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```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>"
      }
    }
  }
}
```

## Tools

- `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.

## 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.

## Alternatives

- [battlemap-mcp](https://ai-powered.com/mcp/battlemap-mcp): battlemap-mcp is an open-source MCP server for games and play.

---
Source: https://ai-powered.com/mcp/map-traveler-mcp
