flipper-mcp
Enables AI agents to debug Android apps through Flipper, including inspecting network requests, logcat, view hierarchies, SharedPreferences, Flux actions, and invoking Flipper plugin methods.
Provides tools to list and query SQLite databases exposed by the Android app's Flipper Databases plugin, including applying writes and returning flattened values.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
flipper-mcp
Servidor MCP para que un agente de IA depure una app Android usando Flipper.
Se conecta a un flipper-server que ya esté corriendo (npx flipper-server, la UI web) como un
cliente más, acumula en memoria los eventos que la app empuja (red, logs, cambios de preferencias,
vistas, acciones Flux) y los expone como tools con filtros y salida JSON compacta.
Protocolo usado: PROTOCOL.md.
Flipper está archivado: las versiones están fijadas a
flipper-server-client@0.273.0/flipper-common@0.273.0, que es lo que instalanpx flipper-serverhoy.
Requisitos
Node.js ≥ 18 para correr el servidor (el desarrollo y los tests usan el Node de
.nvmrc).flipper-server0.273.0 corriendo:npx flipper-server(abre la UI enhttp://localhost:52342). Al arrancar por primera vez crea el token en~/.flipper/certs/auth.token.La app con el SDK de Flipper en el build debug. Para la jerarquía de vistas, el plugin UI Debugger (ver Configurar la app).
Related MCP server: adb-mcp
Instalación
git clone https://github.com/guidomodarelli/flipper-mcp.git
cd flipper-mcp
pnpm install # compila a dist/ en el prepareConfigurarlo en un cliente MCP
El servidor usa stdio. Los clientes MCP no le pasan tu entorno al proceso: las variables van en la config del cliente.
Claude Code
claude mcp add flipper -- node /ruta/a/flipper-mcp/dist/index.js
# con variables:
claude mcp add flipper -e FLIPPER_PORT=52342 -- node /ruta/a/flipper-mcp/dist/index.jsCursor (.cursor/mcp.json) y cualquier cliente con el formato mcpServers:
{
"mcpServers": {
"flipper": {
"command": "node",
"args": ["/ruta/a/flipper-mcp/dist/index.js"],
"env": {"FLIPPER_HOST": "localhost", "FLIPPER_PORT": "52342"}
}
}
}En Windows usá rutas con / o \\ escapadas (C:/Users/vos/flipper-mcp/dist/index.js).
El proceso es persistente: arranca con el cliente MCP, se conecta al server y empieza a guardar
eventos desde ese momento. Lo que pasó antes no se ve. Si flipper-server o la app se caen, se
reconecta solo.
Variables de entorno
Variable | Default | Para qué |
|
| Host del |
|
| Puerto del |
|
| Token JWT; se relee en cada reconexión. |
| — | Token explícito (tiene prioridad sobre el archivo). |
|
| Líneas de logcat guardadas. |
|
| Requests HTTP guardadas. |
|
| Acciones Flux guardadas. |
|
| Cambios de SharedPreferences guardados. |
|
| Tamaño de los bodies si no se pide |
|
| Bodies más grandes no se guardan (solo su tamaño). |
|
| Corte de cada mensaje de log. |
|
| Header HTTP que se toma como |
|
| Plugins que el MCP activa al conectarse la app. |
|
| Cada cuánto re-activa esos plugins (la UI web los desactiva al cambiar de pestaña). |
|
| Timeout de cada comando al server. |
| — | Archivo JSONL donde grabar cada frame WS (también |
Tools
Todas aceptan app (id de list_apps, nombre o paquete); se puede omitir si hay una sola app.
Los tiempos (since, until, changesSince) aceptan epoch ms, relativos ("30s", "5m", "1h")
o ISO. Las listas devuelven {items, matched, truncated, lastId}: pasá lastId como afterId para
traer solo lo nuevo.
Tool | Qué devuelve |
| Estado de la conexión, uso de buffers y dispositivos. |
| Apps conectadas, sus plugins y errores del handshake. |
| Requests sin bodies. Filtros: |
| Headers y bodies decodificados (base64 + gzip/br) de una request; truncados salvo |
| Árbol podado del UI Debugger: |
| Logcat. |
| Bases SQLite del plugin Databases; |
| Estado actual (todos los archivos o |
| Espera |
| Llama cualquier método de cualquier plugin y devuelve la respuesta cruda. |
Con el plugin FluxDispatcher en la app (fase 2):
Tool | Qué devuelve |
| Acciones despachadas, con los stores que cambió cada una y su diff (ops estilo JSON Patch). Filtros: |
| Estado actual de un store, o solo el subárbol de |
| Reemplaza el estado de un store; la UI se vuelve a renderizar. |
| Despacha |
| Guarda el estado de los stores y lo restaura (los snapshots viven en el proceso de la app). |
Los errores vienen con isError y un mensaje que dice qué hacer, por ejemplo
No app connected to flipper-server. Devices available: ["Pixel_7 (emulator-5554)"]. ….
El traceId une Action → request HTTP → cambio de store: la request lleva el header
X-Flux-Trace-Id y la acción de respuesta se despacha con el mismo id (ver android/sample).
Configurar la app
Recomendado: SDK de Flipper 0.273.0 (el último publicado; coincide con el server) y el plugin
UI Debugger en lugar del Layout Inspector viejo (InspectorFlipperPlugin), que está deprecado y
no lo soporta get_view_hierarchy.
// build.gradle.kts: todo solo en debug
debugImplementation("com.facebook.flipper:flipper:0.273.0")
debugImplementation("com.facebook.flipper:flipper-network-plugin:0.273.0")
debugImplementation("com.facebook.soloader:soloader:0.10.4")
debugImplementation(project(":flux-flipper")) // android/flux-flipper de este repo
// src/debug/…/DebugTools.kt
SoLoader.init(app, false)
if (FlipperUtils.shouldEnableFlipper(app)) {
val network = NetworkFlipperPlugin() // + addNetworkInterceptor(FlipperOkhttpInterceptor(network))
val flux = FluxDispatcherFlipperPlugin(
stores = listOf(FluxStoreBinding("SessionStore", SessionState::class.java, { sessionStore.state }, sessionStore::replaceState)),
dispatchAction = { type, payloadJson -> dispatcher.dispatch(actionFrom(type, payloadJson)) },
)
dispatcher.interceptor = DispatchInterceptor { action, proceed -> flux.trace(action.type, action.payload, proceed) }
AndroidFlipperClient.getInstance(app).apply {
addPlugin(UIDebuggerFlipperPlugin(UIDContext.create(app)))
addPlugin(network)
addPlugin(DatabasesFlipperPlugin(app))
// Listá los archivos: si no, el plugin solo ve los que ya existen al arrancar.
addPlugin(SharedPreferencesFlipperPlugin(app, listOf(SharedPreferencesDescriptor("session_prefs", MODE_PRIVATE))))
addPlugin(flux)
start()
}
}
// src/release/…/DebugTools.kt: la misma API sin Flipper.Para un Dispatcher propio solo hacen falta dos ganchos:
Envolver cada dispatch con
flux.trace(type, payload) { … }. Toma el estado de los stores antes y después y manda la acción con el diff y eltraceId.Propagar el
traceId:FluxTrace.current()dentro del dispatch, agregarlo como headerFluxTrace.HEADERa la request, y despachar la respuesta dentro deFluxTrace.runWith(id) { … }en el hilo donde se despacha (si el Dispatcher hacepostal main thread, elrunWithva dentro delpost, porque es unThreadLocal).
El estado se serializa con Gson (FluxStoreBinding.stateClass se usa para set_store_state y
restore_stores; sin setState el store es de solo lectura). Un ejemplo completo y probado está en
android/sample (Dispatcher, Actions, Stores y Views al estilo Flux).
Probar con un emulador
Lo que se usó para validar todo de punta a punta en Windows:
JDK 17, Android SDK (
platform-tools,emulator,platforms;android-34,system-images;android-34;google_apis;x86_64) en%LOCALAPPDATA%\Android\Sdk, que es dondeflipper-serverbuscaadbpor defecto, y un AVD:avdmanager create avd -n flipper34 -k "system-images;android-34;google_apis;x86_64" -d pixel_6.OpenSSL 1.1.1 para
flipper-server. Con el OpenSSL 3.5 que trae Git for Windows el intercambio de certificados falla conX509_REQ_verify_ex:unsupported versiony la app nunca conecta: OpenSSL 3.5 rechaza la versión del CSR que genera el SDK. Con 1.1.1w funciona (no probé versiones intermedias). Poné OpenSSL 1.1.1 primero en elPATHdel server, con suOPENSSL_CONF:export PATH="/ruta/openssl-1.1/x64/bin:$PATH" OPENSSL_CONF="/ruta/openssl-1.1/ssl/openssl.cnf" npx flipper-server@0.273.0cd android && ./gradlew :sample:installDebug, con el emulador corriendo.pnpm build && ADB=<ruta a adb> node scripts/live.mjs recordings/live.jsonl: reinicia la app, toca botones con las coordenadas que devuelveget_view_hierarchyy recorre todas las tools con chequeos (correlación portraceId, texto de las vistas, preferencias,dispatch_action,set_store_state, snapshot/restore).node scripts/deinit-check.mjs: simula que la UI web desactivaui-debuggeryFluxDispatchery verifica que el MCP los vuelve a activar.
Grabar tráfico real
node dist/index.js --record recordings/sesion.jsonlCada línea es {t, dir: "in"|"out", frame}. Copiá la grabación a fixtures/recordings/ y
pnpm test la reproduce contra el server falso (src/replay.test.ts).
Desarrollo
pnpm typecheck
pnpm test # unitarios (buffers, filtros) + integración con un flipper-server falso
pnpm build
node scripts/smoke.mjs # contra un flipper-server real en localhost:52342src/flipper/— conexión (FlipperConnection), protocolo de apps (FlipperBridge), grabación.src/stores/— un store por fuente de eventos, sobresrc/buffer/RingBuffer.ts.src/mcp/— definición de las tools.src/test-support/—FakeFlipperServer(mismos sobres que 0.273.0) y fixtures.android/flux-flipper— pluginFluxDispatcher(Kotlin);cd android && ./gradlew :flux-flipper:testDebugUnitTest.android/sample— app Flux de ejemplo con Flipper solo en debug.
Estado
Fase 1 (MVP) y fase 2 (
FluxDispatcher) implementadas y probadas contra unflipper-server0.273.0 real con la app de ejemplo en un emulador Android 14.fixtures/recordings/live-sample-app.jsonles una sesión real grabada con--record; los tests la reproducen contra el server falso.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Give your AI agent a real cloud Android phone: push APKs, drive it, get screenshots and logs.
Email inboxes, webhook URLs, mock APIs and 170+ tools for coding agents over one MCP connection.
A registry of AI agent tools — MCP servers, APIs, CLIs, SDKs — kept current by automated ingestion.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables MCP-compatible agents to control an Android device over the network via ADB, providing tools for shell commands, screen capture, UI inspection, file operations, and input simulation.4 npmMIT
- AlicenseBqualityCmaintenanceA comprehensive MCP server for Android Debug Bridge, enabling AI agents to control Android devices through structured tools like launching apps, UI automation, file operations, and log capture.907MIT
- AlicenseNot gradedqualityCmaintenanceProvides structured MCP tools for local runtime observability and debugging of React Native/Expo apps on Android, enabling evidence-first diagnostics such as screenshots, UI trees, per-request network capture, performance metrics, and CDP-based console/heap/profiling exports.Apache 2.0
- AlicenseCqualityBmaintenanceExposes Android device automation tools to MCP clients, letting AI agents inspect UI trees, interact with elements, launch/stop apps, run shell commands, transfer files, and manage events/tasks over adb/uiautomator2 without installing anything on the device.60MIT