android-mock-location
MCP server for Android mock location testing
Installation
npx android-mock-location-mcpAsk AI about android-mock-location
Powered by Claude Β· Grounded in docs
I know everything about android-mock-location. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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
