Vemtra Mock Location MCP Bridge

Command MCP bridge for Vemtra Mock Location GPS on Google Play.

Vemtra is an Android mock location app for developers and testers who need predictable GPS simulation. It helps you move a device location from a map, test free-move joystick behavior, run route playback, save favorite locations or routes, and verify apps that depend on Android location providers.

This package lets MCP clients talk to the Vemtra app without configuring a direct http:// Streamable HTTP endpoint. The command runs on your computer as a stdio MCP server, helps the agent inspect adb devices -l, and proxies the live Android app MCP tool list from one connected device at a time.

Requirements

• Node.js 18 or newer.
• Android Debug Bridge (adb) on your PATH.
• A connected Android device with Vemtra installed when you want to call Vemtra app tools.
• Vemtra Mock Location MCP Bridge toggled on in the app.

App Setup

1. Install Vemtra from Google Play.
2. Connect your Android device over USB or wireless ADB.
3. Open Vemtra.
4. Tap the Bot icon beneath the locate icon on the map.
5. Confirm the overlay says Toggle: On.

MCP Client Config

Use this command transport config:

{
  "command": "npx",
  "args": ["-y", "@vemtra/mock-location-mcp-bridge"]
}

Some clients wrap server configs under a named object:

{
  "mcpServers": {
    "vemtra": {
      "command": "npx",
      "args": ["-y", "@vemtra/mock-location-mcp-bridge"]
    }
  }
}

What It Does

On startup, the command exposes only the bridge tools:

• vemtra_get_connection_status: reports whether the host bridge is connected to an Android device and whether the proxy can still reach the Vemtra in-app MCP server.
• vemtra_connect_device: connects one Android device, refreshes the live app-tool list from that device, and tells the caller that their MCP client may need a refresh or agent restart.
• vemtra_list_android_devices: shows the devices visible from adb devices -l. It accepts an optional adbPath.

The bridge also keeps a background monitor running while the command stays open. It checks for a usable local MCP path on 127.0.0.1:8765, auto-attaches when it can safely infer the target device, and publishes tools/list_changed when Android app tools become available or change. Every tools/list request also runs that same best-effort auto-attach flow before it responds, so the first tool listing after startup can include the live Android app tools when the remote path is already available.

After a successful auto-attach or vemtra_connect_device, the bridge appends the current Android app MCP routes from that device to its own tools/list. Those app tools keep the same names and schemas that the Android app exposes.

The usual flow is:

1. Call vemtra_list_android_devices.
2. Pick the exact deviceId from the first column of adb devices -l.
3. Call vemtra_connect_device with that deviceId.
4. If Vemtra's MCP server is not already running, the host bridge sends the in-app MCP-enable intent to that device and tells you to accept the prompt in Vemtra.
5. Refresh your MCP client or restart the agent if the Android app tools do not appear immediately.
6. Call the Android app routes that were loaded from the connected device.
7. Call vemtra_get_connection_status if you need to confirm the proxy is still healthy.

Passive auto-attach uses this order:

1. Reuse an existing adb forward for tcp:8765 -> tcp:8765 when that device is still a healthy device in adb devices -l.
2. Otherwise, if exactly one healthy Android device is visible, create that forward automatically and probe Vemtra.
3. Otherwise, wait for an explicit vemtra_connect_device.

Passive monitoring never sends the in-app MCP-enable intent on its own. Use vemtra_connect_device when you need to force a specific device or request app approval.

If adb is not on PATH, pass an adbPath argument on bridge tool calls:

{
  "adbPath": "/absolute/path/to/adb"
}

Example vemtra_connect_device request:

{
  "deviceId": "55311JEBF06019"
}

Use the exact first-column value from adb devices -l, including wireless ids such as 192.168.1.25:5555.

After a successful connect, the bridge routes Android app tool calls through the connected device. For plot_route and run_route, send at least two stops. Vemtra accepts either plain string place queries, coordinate objects, or a mix of both:

String-stop example:

{
  "stops": [
    "Statue of Liberty National Monument, New York, NY",
    "Liberty Island Museum, New York, NY"
  ]
}

Coordinate-stop example:

{
  "stops": [
    { "latitude": 37.79549, "longitude": -122.39371, "name": "Ferry Building" },
    { "latitude": 37.76802, "longitude": -122.38778, "name": "Chase Center" }
  ]
}

Mixed-stop example:

{
  "stops": [
    "Ferry Building, San Francisco, CA",
    { "latitude": 37.76802, "longitude": -122.38778, "name": "Chase Center" }
  ]
}

String stops require a saved Google Places API key and Google Places enabled in Vemtra Settings > Google. If Google place lookup is unavailable, resend those stops as coordinate objects.

For each Android app tool call, the bridge runs:

adb -s <deviceId> forward tcp:8765 tcp:8765

Then it forwards the MCP request to:

http://127.0.0.1:8765/mcp

The Android app stays in control of the actual app-side MCP server. The npm package is a host-side bridge that remembers one active device connection, keeps probing that same device for recovery, and republishes that device's live app-tool list.

Failure Guidance

The command should stay running for expected local failures. Tool calls return MCP results with isError: true and structured guidance when:

• adb is missing or adbPath is invalid.
• No Android devices are visible.
• The selected device is unauthorized, offline, disconnected, or missing.
• Vemtra is not installed on the selected device.
• adb forward cannot be established.
• The Vemtra app MCP toggle is off or the app bridge returns invalid JSON-RPC. In the common MCP-off case, the host bridge now sends the in-app MCP-enable intent to the device so you can approve it in Vemtra and retry connect.
• More than one healthy Android device is visible and no existing adb forward tcp:8765 tcp:8765 identifies the intended device. In that case, call vemtra_connect_device explicitly.

Options

vemtra-mock-location-mcp-bridge --help

If you run the command directly with no input, it will stay open and wait for MCP JSON-RPC messages on stdin. That is expected for MCP command transport.

For a human-readable smoke test that lists currently visible devices, run:

vemtra-mock-location-mcp-bridge --status

Supported options:

• --adb <path>: adb executable path. Defaults to ADB or adb.
• --port <port>: device and host MCP port. Defaults to 8765.
• --endpoint <url>: forwarded HTTP MCP endpoint.
• --status: show visible ADB devices, then exit.

Release

Publish only this package by running npm from the package directory:

cd packages/mock-location-mcp-bridge
npm pack --dry-run
npm publish --access public

Do not publish from the repository root.

The @vemtra npm scope must exist and your npm account must have permission to publish packages under it. If npm returns Scope not found, create the vemtra organization on npm or change the package name to a scope you control before publishing.

License

MIT