android-mock-location-mcp

Mock Android emulator GPS from any MCP client. Control your emulator's location for QA testing with built-in geocoding and street-level routing.

"Drive from downtown Denver to the airport with rush hour traffic"
"Simulate bad GPS signal for 30 seconds"
"Test the geofence at the nearest Whole Foods - bounce in and out 3 times"

Why?

Testing location-aware apps is painful. You either:

• Manually type coordinates into the emulator's extended controls
• Write complex ADB scripts with hardcoded coordinates
• Use clunky GUI mock location apps

This MCP server lets you control emulator location from Android Studio, Cursor, Claude Code, Codex, etc. Say "drive to the airport" instead of copy-pasting coordinates.

This server controls your Android emulator's GPS with built-in geocoding and street-level routing — it sends geo fix commands directly to the emulator via ADB.

Architecture

┌─────────────────────────────────────────────────────────┐
│  Developer Machine                                      │
│  ┌───────────────┐      ┌─────────────────────────────┐ │
│  │ Claude/Cursor │ ←──→ │ MCP Server                  │ │
│  │ or any MCP    │      │ • Geocoding + routing       │ │
│  │ client        │      │ • Route interpolation       │ │
│  └───────────────┘      │ • geo fix command            │ │
│                          └──────────┬──────────────────┘ │
└────────────────────────────────────┼────────────────────┘
                                     │ adb emu geo fix
                                     ▼
┌─────────────────────────────────────────────────────────┐
│  Android Emulator                                       │
│  GPS location set via geo fix                           │
└─────────────────────────────────────────────────────────┘

Quick Start

1. Configure Your MCP Client

The server is launched automatically by your MCP client — you don't run it directly. Add it to your client's config:

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "android-mock-location-mcp": {
      "command": "npx",
      "args": ["-y", "android-mock-location-mcp"]
    }
  }
}

Cursor

Go to Settings → MCP → Add Server:

{
  "command": "npx",
  "args": ["-y", "android-mock-location-mcp"]
}

Claude Code

claude mcp add android-mock-location-mcp -- npx -y android-mock-location-mcp

Restart your MCP client after updating the config for changes to take effect.

For provider options (Google, Mapbox), see Server Configuration.

2. Start an Emulator

Start an Android emulator from Android Studio or the command line. No special setup is needed — the server communicates directly via geo fix commands.

3. Use It

In your MCP client:

> Set location to Times Square New York
> Drive from here to SFO airport at 60 km/h

The server will automatically detect the emulator and start setting locations.

Available Tools

Tool	Description
geo_set_location	Set to coordinates or place name
geo_simulate_route	Move along a route at specified speed (supports car/foot/bike profiles)
geo_simulate_multi_stop	Multi-stop route with dwell times (e.g. delivery routes)
geo_simulate_jitter	Simulate GPS noise (urban canyon, drift)
geo_test_geofence	Test geofence entry/exit/bounce
geo_replay_gpx_kml	Replay a GPX or KML track file
geo_stop	Stop any active simulation
geo_get_status	Current mock location status
geo_get_location	Get emulator's current GPS position (for use as route starting point)
geo_list_devices	List connected Android emulators
geo_connect_device	Connect to specific emulator

For full parameter reference, see server/README.md.

Provider Configuration

Works out of the box with OpenStreetMap (free, no API key). For better results, consider using Google or Mapbox providers — they offer more accurate geocoding, full routing profile support (car/foot/bike), and higher rate limits.

Provider	Pros	Limitations	Get an API Key
osm (default)	Free, no API key needed	Car routing only, 1 req/sec geocoding limit	—
google	Accurate geocoding, full car/foot/bike routing	Requires API key (has free tier)	Google Maps Platform
mapbox	Accurate geocoding, full car/foot/bike routing	Requires access token (has free tier)	Mapbox Access Tokens

For env vars, MCP client config examples, and provider details, see server/README.md.

Examples

# Basic location
"Set location to 37.7749, -122.4194"
"Move to Times Square"

# Route simulation
"Drive from SFO to downtown SF, simulate a commute with heavy traffic"
"Walk to the nearest Whole Foods"

# Multi-stop routes
"Simulate a delivery route: warehouse → Stop A (wait 30s) → Stop B (wait 30s) → depot"

# Track replay
"Replay this GPX file from my morning run at 2x speed"

# GPS testing
"Simulate bad GPS for 30 seconds, add urban canyon jitter with 50m radius"

# Geofence testing
"Test entering the nearest Starbucks geofence, bounce in and out of a 100m radius 5 times"

Documentation

Document	Description
Server README	Tool reference, provider configuration, development
Publishing	npm publish and release workflow
Contributing	Development setup

Complementary Tools

This server focuses on emulator location control. For other needs:

• mobile-mcp — Cross-platform (iOS + Android) mobile UI automation
• Android-MCP — Lightweight Android device control via ADB + Accessibility API

License

Apache 2.0 — see LICENSE