Virtual location (Google Street View,etc.)

What is map-traveler-mcp?

map-traveler-mcp is an MCP (Multi-Agent Communication Protocol) server that creates an environment for an avatar to virtually travel on Google Maps. It integrates with Google Map, Google Street View, PixAI, Stability.ai, ComfyUI API, and Bluesky to provide a virtual location simulation within an LLM (Large Language Model) environment.

How to use map-traveler-mcp?

There are two main modes of use: Practice Mode and Full Feature Mode.

Practice Mode

1. Install Node.js 22.
2. Set up Claude Desktop.
3. Configure claude_desktop_config.json with the practice mode settings.
4. Restart Claude Desktop.
5. Interact with the bot by asking questions like "Where are you now?" or giving commands like "Go on a journey."
6. Attach role.txt from MCP resources to enable Claude to act as a traveler.

Full Feature Mode

1. Obtain and set Google Map API keys (Street View Static API, Places API (New), Time Zone API, Directions API).
2. Configure sqlite_path in claude_desktop_config.json to save travel logs.
3. Install Python 3.7-3.11 and rembg cli (virtual environment recommended).
4. Set rembg_path in claude_desktop_config.json.
5. Obtain and set an image generation API key (PixAI or Stability.ai) in claude_desktop_config.json.
6. Optionally, set Bluesky SNS credentials for automatic posting.

LibreChat Integration

map-traveler-mcp can also be integrated with LibreChat, requiring Docker for rembg and specific configurations in librechat.yaml and .env files. Agents need to be configured within LibreChat to utilize the map-traveler-mcp tools.

Smithery Integration

map-traveler-mcp supports remote use from Smithery, allowing travel progress to be saved with Turso sqlite if configured.

Key Features of map-traveler-mcp

• Virtual Travel Simulation: Simulates an avatar traveling on Google Maps and Google Street View.
• API Integrations: Seamlessly integrates with Google Maps, Google Street View, PixAI, Stability.ai, ComfyUI, and Bluesky.
• Interactive Commands: Provides functions to get current location, set destination, start/stop journeys, and get/set traveler attributes.
• Image Generation: Generates and overlays avatar images on travel photos using AI models.
• Social Media Integration: Posts travel updates and interacts on Bluesky SNS.
• Customizable Prompts: Allows setting custom prompts for avatar image generation and traveler personality.
• Flexible Deployment: Can be used with Claude Desktop, LibreChat, and Smithery.
• Database Support: Supports local SQLite and Turso libsql for persistent travel logs.

Use Cases of map-traveler-mcp

• Interactive Storytelling: Create dynamic narratives where an AI avatar explores virtual locations.
• Educational Tool: Visualize geographical locations and simulate journeys for learning purposes.
• Gaming: Develop novel games where AI agents interact and compete based on virtual travel.
• Social Media Automation: Automatically generate and post travel content to social media platforms.
• Personalized Virtual Experiences: Offer users a personalized virtual travel companion.

FAQ from map-traveler-mcp

• What APIs are required? Google Map API (Street View Static, Places, Time Zone, Directions) is essential. Image generation APIs (PixAI, Stability.ai) and Bluesky SNS are optional.
• Is rembg necessary? Yes, for avatar image overlay. It can be installed locally or used via a service API (e.g., withoutbg.com).
• Can I use my own image generation model? Yes, you can integrate with a local ComfyUI instance for more control over image generation.
• How do I save my travel progress? By configuring the sqlite_path for local storage or using Turso libsql for cloud storage.
• Can I run it without an API key for verification? Yes, practice mode allows basic functionality without API keys.
• What is the MT_NO_IMAGE setting? This setting allows you to disable image generation and output, useful for MCP clients without image input/output capabilities or to reduce API costs.

Virtual Traveling bot environment for MCP

English / Japanese

This is an MCP server that creates an environment for an avatar to virtually travel on Google Maps.

From an MCP client such as Claude Desktop, you can give instructions to the avatar and report on the progress of its journey with photos.

Now supports librechat https://www.librechat.ai/.

Now supports Smithery https://smithery.ai/server/@mfukushim/map-traveler-mcp (images are excluded because they are heavy to run).

Now verified MseeP https://mseep.ai/app/mfukushim-map-traveler-mcp

Functions

MCP server tools function

The following functions can be used as an MCP server. The available functions vary depending on the settings and execution state.

You can specify the function name directly, but Claude LLM will automatically recognize it, so you can specify the operation in general terms.

Example: "Where are you now?" "Let's leave for Tokyo Station."

• get_traveler_view_info(includePhoto:boolean,includeNearbyFacilities:boolean)
  Gets information about the current travel avatar's location.
  • includePhoto: Gets nearby Google Street View photos. If you have set up an image generation AI, it will synthesize the avatar.
  • includeNearbyFacilities: Gets information about nearby facilities.
• get_traveler_location()
  Gets information about the current travel avatar's address and nearby facilities.
• reach_a_percentage_of_destination() Reach a specified percentage of the destination (moveMode=skip only) timeElapsedPercentage: Percent progress towards destination(0~100)
• set_traveler_location(address: string)
  Sets the current travel avatar's location.
  • address: Address information (exact address, or general name that Google Maps or Claude can recognize, etc.)
• get_traveler_destination_address
  Get the destination of the travel avatar you set
• set_traveler_destination_address(address: string)
  Set the destination of the travel avatar
  • address: Address information (exact address, or general name that Google Maps or Claude can recognize, etc.)
• start_traveler_journey
  Start the journey at the destination.(moveMode=realtime only)
• stop_traveler_journey
  Stop the journey.(moveMode=realtime only)
• set_traveler_info(settings:string)
  Set the traveler's attributes. Set the traveler's personality that you want to change dynamically, such as name and personality. However, if you use a role script, the script is more stable.
  • settings: Setting information such as name and personality.
• get_traveler_info
  Get the traveler's attributes. Get the traveler's personality.
• set_avatar_prompt(prompt:string)
  Set the prompt when generating the travel avatar image. The default is an anime-style woman. The anime style is enforced to prevent fake images.
  • prompt
• reset_avatar_prompt
  Reset avatar generation prompts to default.
• get_sns_feeds
  Gets Bluesky SNS articles for the specified custom feed (feeds containing a specific tag).
• get_sns_mentions
  Gets recent mentions (likes, replies) to Bluesky SNS posts that you made yourself.
• post_sns_writer(message:string)
  Posts an article to Bluesky SNS with the specified custom feed. Set a specific tag so that it can be determined that the post was generated by the travel bot.
  • message: article
• reply_sns_writer(message:string,id:string)
  Reply to the article with the specified id. Set a specific tag so that it can be determined that the post was generated by the travel bot.
  • message: reply
  • id: The ID of the post to reply to
• add_like(id:string)
  Add a like to the specified post.
  • id: The ID of the post to like
• tips
  Guides you on how to set up features that have not yet been set.
• get_setting
  Get environment and image settings.

MCP resources

Has five custom prompt samples. When you import a prompt with Claude Desktop, Claude will act as a traveler. The SNS-compatible version controls SNS input and output while having a travel conversation.

• role.txt
  Claude will act as a traveler.

• roleWithSns.txt
  Claude will act as a traveler. It also controls reading and posting to SNS.

• carBattle.txt
  This is a small novel game about a story of transporting secret documents from Yokohama to Tokyo. Scenes are automatically generated. Set moveMode=skip to play.

• japanMapChallenge.txt,japanMapChallenge2.txt
  Two AIs communicate with each other via SNS and play a challenge game using landscape images.
  To play, you need two Bluesky accounts and two Claude Desktops. Also set moveMode=skip. (However, the operation is somewhat unstable.)
  japanMapChallenge2 has a challenge reflection rule.

Setting

You will need to obtain and set access keys for multiple APIs, such as for accessing multiple Google maps and generating images. Use of the API may incur charges.

Settings for using with Claude Desktop

claude_desktop_config.json

{
  "mcpServers": {
    "traveler": {
      "command": "npx",
      "args": ["-y", "@mfukushim/map-traveler-mcp"],
      "env":{
        "MT_GOOGLE_MAP_KEY":"(Google Map API key)",
        "MT_MAP_API_URL": "(Optional: Map API custom endpoint. Example: direction=https://xxxx,places=https://yyyy )",
        "MT_TIME_SCALE": "(Optional:Scale of travel time on real roads duration. default 4)",
        "MT_SQLITE_PATH":"(db save path: e.g. %USERPROFILE%/Desktop/traveler.sqlite ,$HOME/traveler.sqlite )",
        "MT_TURSO_URL":"(Turso sqlite API URL)",
        "MT_TURSO_TOKEN":"(Turso sqlite API access token)",
        "MT_REMBG_PATH": "(absolute path of the installed rembg cli)",
        "MT_REMBG_URL": "(rembg API URL)",
        "MT_REMBG_WO_KEY": "(withoutbg.com rembg API key)",
        "MT_PIXAI_KEY":"(pixAi API key)",
        "MT_SD_KEY":"(or Stability.ai image generation API key",
        "MT_PIXAI_MODEL_ID": "(Optional: pixAi ModelId, if not set use default model 1648918127446573124 ",
        "MT_COMFY_URL": "(Option: Generate image using ComfyUI API at specified URL. Example: http://192.168.1.100:8188)",
        "MT_COMFY_WORKFLOW_T2I": "(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": "(Optional: Path of API workflow file when image to image in ComfyUI. If not specified: assets/comfy/i2i_sample.json)",
        "MT_COMFY_PARAMS": "(Optional: Variable values to send to the workflow via comfyUI API)",
        "MT_FIXED_MODEL_PROMPT": "(Optional: Fixed avatar generation prompt. You will no longer be able to change your avatar during conversations.)",
        "MT_BODY_AREA_RATIO": "(Optional: Acceptable avatar image area ratio. default 0.042)",
        "MT_BODY_HW_RATIO": "(Optional: Acceptable avatar image aspect ratios. default 1.5~2.3)",
        "MT_BODY_WINDOW_RATIO_W": "(Optional: Avatar composite window horizontal ratio. default 0.5)",
        "MT_BODY_WINDOW_RATIO_H": "(Optional: Avatar composite window aspect ratio. default 0.75)",
        "MT_BS_ID":"(Bluesky sns registration address)",
        "MT_BS_PASS":"(bluesky sns password)",
        "MT_BS_HANDLE":"(bluesky sns handle name: e.g. xxxxxxxx.bsky.social )",
        "MT_FILTER_TOOLS": "(Optional: Directly filter the tools to be used. All are available if not specified. e.g. tips,set_traveler_location)",
        "MT_MOVE_MODE": "(Option: Specify whether the movement mode is realtime or skip. default realtime)",
        "MT_IMAGE_WIDTH": "(Option: Output image width (pixels) Default is 512)",
        "MT_NO_IMAGE": "(Options: true = do not output image, not specified = output image if possible, default is not specified)",
        "MT_FEED_TAG": "(Optional: Specify the feed tag when posting to SNS (#required, 15 characters or more) Default is #geo_less_traveler)"
      }
    }
  }
}

NOTE: The environment variables have been renamed to standard snake case. The MT_ prefix is ​​added because they may be used in conjunction with other environment variables, such as in librechat. The old names can still be used for backward compatibility.

Please set the following three Credentials for Google Map API.

• Street View Static API
• Places API (New)
• Time Zone API
• Directions API

https://developers.google.com/maps/documentation/streetview/get-api-key

If you want to use the image generation AI, set either pixAi_key or sd_key. You also need to have python3.7~3.11 installed on your PC and rembg cli installed (virtual environment recommended).

https://platform.pixai.art/docs
https://platform.stability.ai/docs/api-reference#tag/SDXL-1.0-and-SD1.6/operation/textToImage

The bluesky SNS address/password are optional. It is recommended that you create a dedicated account as it will post automatically.

https://bsky.app/

You can also run it in practice mode, which does not require an API key for verification.

Practice mode settings

claude_desktop_config.json

{
  "mcpServers": {
    "traveler": {
      "command": "npx",
      "args": ["-y", "@mfukushim/map-traveler-mcp"]
    }
  }
}

How to use

Use the practice mode

1. Install nodejs 22.

2. Set up Claude Desktop for use.

3. Reflect one of the above settings in claude_desktop_config.json.

4. Restart Claude Desktop. It may take some time to set up (if an error occurs, try restarting Claude Desktop again. If it doesn't work, see the notes below). Make sure the following mark appears in the bottom right of the screen.

5. Ask "Where are you now?" and "Go on a journey." A conversation will begin. When using the API, a confirmation screen will appear, so select Allow.

6. Select Attach from MCP and select role.txt.

7. A travel prompt has been built in, so feel free to talk to it.

Use the full feature

1. Get a Google Map API access key and set the permissions for Street View Static API, Places API (New), Time Zone API, and Directions API. Set this in the env of claude_desktop_config.json and restart. At this point, the travel log will be based on the real map. Travel images will also be output if they are not superimposed.
2. Decide on a path that will not interfere with the disk and set it in the sqlite_path of the env of claude_desktop_config.json. (Example: %USERPROFILE%/Desktop/traveler.sqlite $HOME/Documents/traveler.sqlite, etc.) At this point, your travel log will be saved and you can continue your journey even if you close Claude Desktop.
3. Install python 3.7 to 3.11 and install rembg with cli. We recommend using a virtual environment such as venv.

python3 -m venv venv
. venv/bin/activate or .\venv\Scripts\activate
pip install "rembg[cpu,cli]"

Check if rembg cli works properly using a sample image file. Input an image with a person in it, and if the person is cut out in the output file, it's OK.

rembg i source_image_file dest_image_file

4. rembg cli will be installed in the python exe location, so get the path. The file location varies depending on the OS and python installation status, but in the case of venv, it is (virtual environment name)\Scripts\rembg.exe or (virtual environment name)/bin/rembg above the directory you set. If you can't find it, search for the path with a file search software. Set that path to rembg_path of env in claude_desktop_config.json. (Example: "rembg_path": "C:\Users\xxxx\Documents\rembg_venv\venv\Scripts\rembg.exe")
5. Get an image generation API key from the pixAI or Stability.ai site. Set the key to pixAi_key or sd_key in env of claude_desktop_config.json. The avatar will now be overlaid on the travel image.
6. Get the bluesky SNS address/password and handle name. Set these in bs_id, bs_pass, and bs_handle in env of claude_desktop_config.json, respectively. Import the travel knowledge prompt roleWithSns.txt to report travel actions to SNS (it will automatically post as a bot, so we recommend allocating a dedicated account)

Instead of preparing rembg with the cli, we have added a setting that allows you to handle rembg as a service API.
If you configure the following rembg service, you can use rembg by setting the URL in remBgUrl.

https://github.com/danielgatis/rembg?tab=readme-ov-file#rembg-s

Setup is simple if you use the Docker version to launch a container and access it.

https://github.com/danielgatis/rembg?tab=readme-ov-file#usage-as-a-docker

Use Turso libsql API for configuration database

If you want to use the cloud API Turso libsql (https://turso.tech/libsql) without having a local sqlite file, sign up for Turso and allocate a sqlite database (paid, free tier available).
This add-in will automatically configure (migrate) the database.
MT_TURSO_URL = turso db URL
MT_TURSO_TOKEN = turso db access token

Use Cloud API for rembg

Local settings around rembg are complicated no matter what method you use, but we have added settings for the paid cloud rembg (https://withoutbg.com/).

Note: There is a small free trial available, but please be aware that this is a commercial API and is quite expensive (about 0.1 euros per image).

MT_REMBG_WO_KEY = withoutbg access token

When using external ComfyUI (for more advanced users)

You can also use a local ComfyUI as an image generation server. You can configure the image generation characteristics yourself in detail to reduce API costs.

However, the configuration will be quite complicated and image generation may take longer.

1. Configure ComfyUI to run in API mode.
2. Set the server URL to comfy_url in env.
3. Set detailed configuration values such as the model to be used in env in the form of a json string. example.

{
  "env": {
    "comfy_url": "http://192.168.1.100:8188",
    "comfy_workflow_t2i": "C:\\Documents\\t2itest.json",
    "comfy_workflow_i2i":"C:\\Documents\\i2itest.json",
    "comfy_params":"ckpt_name='animagineXL40_v40.safetensors',denoise=0.65"
  }
}

4. The default workflow can use assets/comfy/t2i_sample.json and assets/comfy/i2i_sample.json in the package. You can specify variables using % and specify the variables in comfy_params.

Using libreChat

It has been adapted to work with libreChat. This makes it easier to use, but some additional settings are required.
Also, it seems that it will not be stable unless the PC you use has a decent level of performance, such as one that can stably run Docker.

Install libreChat

Please make sure it works as described on the official website.
In this case, we recommend using Docker configuration due to additional settings.

https://www.librechat.ai/docs/local/docker

Configure librechat.yaml using the official procedure.
I think you will need to add a local or API LLM service.

https://www.librechat.ai/docs/configuration/librechat_yaml

Add a user for login.

https://www.librechat.ai/docs/configuration/authentication#create-user-script

Please set it so that you can have general chat conversations.

Add a rembg container with additional settings

To use rembg with Docker, add pulling and running the rembg Docker container.

docker-compose.override.yml

 services:
   api:
     volumes:
       - type: bind
         source: ./librechat.yaml
         target: /app/librechat.yaml

   rembg:
     image: danielgatis/rembg:latest
     restart: always
     command: "s --host 0.0.0.0 --port 7000 --log_level info"

Add map-traveler-mcp to the MCP service

Add librechat.yaml

mcpServers:
  traveler:
    type: stdio
    command: npx
    args:
      - -y
      - "@mfukushim/map-traveler-mcp"

Add .env (Same as env in claude_desktop_config.json)

# map-traveler-mcp
GoogleMapApi_key=(Google Map API key)
sqlite_path=/home/run_test.sqlite (e.g. librechat in an unobtrusive location inside the container, or in an external directory that you don't want to mount.)
remBgUrl=http://rembg:7000 (rembg Service API URL, container URL)
(Other settings such as image generation AI settings, PixAI key, stability.ai API key, ComfyUI settings, etc.)

After setting, restart the container.
On slow PCs, mcp initialization may fail. Multiple restarts may work, but this may be difficult to run...

llibreChat settings

To use the MCP function in libreChat, use the Agents function.

1. On the conversation screen, select Agents.
   
2. Select Agent Builder from the panel on the right side of the screen and configure your agent.
   
3. Select Add Tools to use map-traveler.
   
4. The agent tools screen will appear, so select and add all the map-traveler-mcp tools (if the map-traveler-mcp tools are not listed, MCP initialization has failed, so please restart the container or review the settings by checking the logs, etc.)
   
   
5. Enter additional script in the instruction area.
   Since libreChat does not have the MCP resource function, enter the content text of the following URL into the instruction area instead.
   https://github.com/mfukushim/map-traveler-mcp/blob/main/assets/scenario/role.txt
   
6. Click the Create button to save the agent.
   
7. Start a new chat.

Smithery

Please refer to https://smithery.ai/server/@mfukushim/map-traveler-mcp.
Remote MCP (stdio mode) is supported, but the configuration feature has been removed because image generation was too heavy to run.
Database settings can now be recorded with Turso sqlite, so if you configure Turso, your travel progress will also be saved.

Install guide (Japanese, but lots of photos)

1. introduction and Practice mode
   https://note.com/marble_walkers/n/n7a8f79e4fb30
2. DB, Google Map API, Image gen API
   https://note.com/marble_walkers/n/n765257c27f3b
3. Avatar prompt
   https://note.com/marble_walkers/n/nc7273724faea
4. SNS integration
   https://note.com/marble_walkers/n/na7c956befe7b
5. Application 1
   https://note.com/marble_walkers/n/n3c86edd8e817
6. ComfyUI API
   https://note.com/marble_walkers/n/ncefc7c05d102
7. Application 2
   https://note.com/marble_walkers/n/ne7584ed231c8
8. LibreChat setting
   https://note.com/marble_walkers/n/n339bf7905324
9. AI Agent SNS Battle Map Challenge
   https://note.com/marble_walkers/n/n6db937573eaa
10. Support Smithery, Turso libSQL, and rembg API
    https://note.com/marble_walkers/n/ne3b3c0f99707

Additional about the source code

I use Effect.ts to simplify error management & for my own learning.
We also use the Effect Service, but due to the way MCP calls work, we believe that consolidating it using the Service was not optimal.
I think it would be simpler to handle the MCP calls directly in the Effect.
Addendum: I'm aware that I will be able to reconsider how to use the Effect Service and rewrite it neatly, but I'm still considering whether to rewrite it.

Notes on the latest updates

• Added image_width to env. The default is 512. Setting it smaller may reduce the cost of LLM API.
• Added an env setting that does not output images for MCP clients that do not have image input/output.
  "MT_NO_IMAGE": "true" will not generate or output any images. Other image-related settings can be omitted.

{
  
  "env": {
    "MT_NO_IMAGE": "true"
  }
  
}
or
{
  
  "env": {
    "GoogleMapApi_key": "xxxx",
    "MT_NO_IMAGE": "true"
  }
  
}

• You can now specify the tag name to be added when posting to SNS (Bluesky). #Required and must be at least 15 characters. If not specified, it will become "#geo_less_traveler".

• The information obtained from SNS has been slightly changed. The information posted to SNS has been slightly changed.

• A script has been added that allows multiple travel bots to converse and play via SNS.

• Supports remote use from Smithery.
  If you do not want to configure detailed settings, start the app in practice mode. You can also run the app at full speed by configuring each cloud API, but please be aware of charges as it uses many paid APIs such as rembg API. If you do not want to synthesize avatars, you can run the app with the minimum settings of Google Map API and Turso sqlite API.