unidbg

unidbg exposes an MCP (Model Context Protocol) server to enable AI-assisted debugging and tooling for emulated Android native libraries. With MCP enabled, AI tools (such as Cursor) can connect to the server to inspect state, run targeted analyses, and guide reverse engineering or testing workflows within the emulator. The server wires into the emulator to expose capabilities like listing modules, inspecting memory and registers, controlling execution, and invoking native functions, all while collecting backtraces and runtime state for AI-assisted analysis. Typical usage involves starting the MCP server when the debugger is attached and then configuring your AI tool to connect to the provided SSE/HTTP endpoint to begin interactive analysis or scripted tool runs.

Once connected, you can leverage the available MCP Tools to inspect modules, read/write memory, set breakpoints, disassemble code, trace execution, and call native functions. For example, you can query loaded modules, locate a symbol, then use call_function or call_symbol to trigger native code paths and observe behavior under controlled inputs. The toolkit also supports custom MCP tools via McpToolkit, enabling repeatable experiments where you invoke a specific native routine with varying parameters while the AI assistant maintains context across runs.

Prerequisites:

• Java Development Kit (JDK 11 or newer)
• Maven or Gradle build tooling (depending on project setup)
• Git

Installation steps:

1. Clone the repository: git clone https://github.com/zhkl0228/unidbg.git cd unidbg
2. Build the project (example using Maven): mvn -U -DskipTests package // or using Gradle if the project uses Gradle: ./gradlew build -x test
3. Verify the build artifacts exist (e.g., jar files) in the target/build directory.
4. Start the MCP-enabled server component (see mcp_config for command). Example (adjust paths): node path/to/unidbg-mcp-server.js
5. Confirm the server is listening on the configured port (default 9239).
6. Connect your MCP-enabled AI tool (e.g., Cursor) to http://localhost:9239/sse or the configured endpoint.

Notes and tips:

• The unidbg MCP server integrates with various backends and supports advanced debugging features like breakpoints, memory tracing, and native function invocation. Ensure the emulator is running with the JNI and native hooks enabled for full functionality.
• If you encounter port conflicts, change the PORT environment variable in the mcp_config entry to an unused port.
• When using custom MCP tools, you can register them via McpToolkit so that the AI can re-run target functions with different parameters without restarting the process.
• Some features rely on native backends and hooks (Dobby, xHook, fishhook, dynarmic, etc.). Make sure the corresponding native components are built for your target architecture (ARM32/ARM64) and platform (Android or iOS).
• For debugging, you may want to enable verbose MCP server logs by setting DEBUG=unidbg-mcp-server:* in the environment.
• If the MCP server starts but the AI tool cannot connect, verify network bindings, firewall rules, and that the server is listening on the expected path (e.g., /sse).