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:

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

Go to Settings → MCP → Add Server:

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

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

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.

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

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