unidbg: an Android emulator whose MCP debugger can write into the process it is analysing
Allows you to emulate an Android native library, and an experimental iOS emulation
At a glance
- What is it?
- A Java emulator for Android native libraries and, experimentally, iOS, built on four execution backends with inline and import hooking delegated to other people's projects. Its Model Context Protocol debugger exposes an SSE endpoint on localhost with tools that write memory, allocate and free blocks, patch instructions, set registers and call functions by address. Two long gaps sit between the three listed releases, and the version has never reached 1.0.
- Who is it for?
- unidbg is serious tooling for anyone who needs a native library to run under Java rather than on a device, and the readme is unusually forthcoming about its boundaries, naming the projects that do its hooking, marking which tools need which backend, and stating plainly that it is educational and to be used at your own risk. Two things deserve attention before you wire it into anything.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 16 days ago.
- What is it written in?
- Mainly Java, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- zhkl0228/unidbg5,323 ★ · +120
| Repository | 2026-09-11 | 2026-11-15 |
|---|---|---|
| zhkl0228/unidbg | 5.2k | 5.3k |
120 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Two long gaps, and the version has never reached 1.0
Three releases are listed, and the spacing between them is the story.
v0.9.7 was published on 2022-07-30. v0.9.8 followed on 2024-09-05, about twenty five months later. v0.9.9 arrived on 2026-03-05, about eighteen months after that. The last push was on 2026-10-30, nearly eight months after the latest tag.
So across the visible range the project has moved three patch versions in nearly four years, and every one of them is still a zero version.
That does not mean the code is stale, because the commits after the newest tag are recent and the feature list is long. It means the tag list is a poor proxy for activity, and that pinning a unidbg version is pinning something that moves in large, irregular steps.
The description itself is the shortest statement of scope on the page: it allows you to emulate an Android native library, and an experimental iOS emulation.
iOS is experimental in the description and a whole module in the tree
The repository description calls the iOS side experimental. Everything else presents it as finished.
The feature list gives iOS its own entries. There are iOS fishhook, substrate and whale hooks, listed together in one line. There is support for the iOS Objective-C and Swift runtimes. And the MCP tool table has an iOS only group, available when the family is iOS, containing tools that inspect an Objective-C message send by showing the receiver class name and selector, get the Objective-C class name of an object, and dump a class definition with its properties, methods, protocols and instance variables.
The tree agrees with the feature list rather than with the description. There are three modules, an api module, an android module and an ios module, sitting beside a backend directory.
So the honest reading is that the Android path is the settled one and the iOS path is a real, structured implementation that the author still describes as experimental. Treat the iOS module as something you test rather than something you depend on.
Four backends, and the tool table says which one each tool needs
Execution is pluggable and the page is specific about the options.
There is a unicorn backend, linked as the author's own fork rather than upstream, and it is the one that carries the developer conveniences: a simple console debugger, a gdb stub, instruction trace, and memory read and write trace. There is a dynarmic backend, described as fast. There is Apple M1 hypervisor support, described as the fastest ARM64 backend. And there is a Linux KVM backend, with the Raspberry Pi 4B named as the machine it was set up with.
The most useful detail is that individual tools declare their own requirements. Two execution tools are marked as available on unicorn only, one that breaks at the next basic block and one that breaks at the next instruction matching a mnemonic. The protocol buffer schema dump is marked as 64 bit only.
That is better disclosure than most projects give. The cost lands on you: a script that works on one backend may quietly lack two execution tools on another, and besides those inline notes, the check_connection tool reports backend capabilities.
The MCP debugger has a write side, and no authentication is described
This is the section to read carefully before turning it on. When the debugger is active you type a command in the console, optionally with a port, and an MCP server starts that an AI tool connects to:
{
"mcpServers": {
"unidbg-mcp-server": {
"url": "http://localhost:9239/sse"
}
}
}Now read the tool table for the write side. The memory group contains write_memory, allocate_memory, free_memory, list_allocations and patch, where patch is described as writing assembled instructions to memory. The registers group contains set_register alongside the getters. The function call group contains call_function, which calls a native function by address with typed arguments given as hex, string, bytes or null, and call_symbol, which calls an exported function by module and symbol.
Read together with the assemble tool, which turns instruction text into machine code, that is a complete ability to modify the emulated program: write a value, patch a function's instructions, then call it.
The endpoint is on localhost, which is the right default, and the readme says to use the project at your own risk. It describes no token, no origin check and no allowlist. On a shared development machine, anything that can reach that port can drive the emulator.
One mode dies with the run, the other keeps the surface alive
The debugger has two operating modes and the difference between them is a lifetime difference.
The first is breakpoint debugging. You attach the debugger and run your code, and when a breakpoint is hit the emulator pauses so you can type the console command and let a tool assist:
Debugger debugger = emulator.attach();
debugger.addBreakPoint(address);Resuming continues, and hitting another breakpoint pauses again. The last part of that mode's description is the important one: once execution completes without hitting a breakpoint, the process exits and the server shuts down.
The second mode registers custom tools through a toolkit, each one implementing a tool interface with a name, a description, parameter names and an execute method. The stated advantage is re-runnability. The native library is loaded once, and after each execution the process stays alive and the server remains active for the next run:
McpToolkit toolkit = new McpToolkit();
toolkit.addTool(new McpTool() {
@Override public String name() { return "encrypt"; }
@Override public String description() { return "Run encryption"; }
@Override public String[] paramNames() { return new String[]{"input"}; }
@Override public void execute(String[] params) {
String input = params.length > 0 ? params[0] : "default";
}
});
toolkit.run(emulator.attach());That is the mode where the read and write tools stay reachable indefinitely, which is what makes it useful for iterating on one target function and also what makes it worth shutting down when you stop.
Hooking is delegated to three separate projects
The feature list credits its hooking rather than claiming it. Inline hooking comes from Dobby. Android import hooking comes from xHook. On the iOS side there are three engines in one line, fishhook, substrate and whale.
So there are five named third party engines behind the hooking surface, and none of them is this project's own work. That is a sensible division for an emulator: inline patching, import table rewriting and Objective-C method swizzling are three different problems, and each has a maintained implementation.
It also has a practical consequence for anyone vendoring the project, since the dependency surface is wider than the readme's first line suggests. The feature list is the only place all five are named, so it is worth reading end to end rather than skimming, particularly if you need to know whether a hook you rely on is present on your target.
Alongside the hooks, the list covers the JNI surface and the instruction set: emulation of the JNI invocation API so that a library's load function can be called, support for the virtual machine and environment objects, emulation of the syscalls instruction, and both ARM32 and ARM64.
Memory leak detection reports both the guest and the host stack
One feature line is about diagnosing the emulator rather than the target, and it is the most specific one on the page: memory leak detection for emulated native code, with a guest backtrace and a host stack trace.
In practice that means when an emulated library leaks, the report names the allocation site in the guest's own call stack and also the Java side that requested it. That separates a leak in the target from a leak in the host bindings, which is exactly the distinction you cannot make by reading the target's own backtrace alone.
That is the kind of feature that only matters once you have run the target long enough to leak, and it is worth knowing about before you build your own harness to find out.
One more detail in the tool table deserves the same attention. The Objective-C class name lookup is annotated as pure memory parsing with no state change, while the class definition dump carries no such note. For a tool an AI agent will call repeatedly in a loop, the difference between a read that cannot disturb the program and a call that can is worth having written down.
Three Maven modules, a wrapper, and a paired test script
The root is a Maven multi-module project, and the module names line up with the architecture described in the readme.
There is a pom.xml, a .mvn directory and both wrapper scripts, mvnw and mvnw.cmd, so the build does not assume a Maven installation. The three modules are unidbg-api, unidbg-android and unidbg-ios. A backend directory sits beside them, which is where the pluggable execution engines would live, and there is an assets directory alongside it.
The same Windows and Unix pairing shows up in the test entry points, a test.sh and a test.cmd at the root. That is a small sign of how this project is actually used, on developer machines of both kinds, rather than only in continuous integration.
The build files themselves are not printed in the readme, so the dependency versions, the Java level and the module wiring are not something you can read without opening the tree. For a project whose selling point is a specific backend and a specific debugger, that is the one thing the readme leaves entirely to the repository.
Editorial conclusion
unidbg is serious tooling for anyone who needs a native library to run under Java rather than on a device, and the readme is unusually forthcoming about its boundaries, naming the projects that do its hooking, marking which tools need which backend, and stating plainly that it is educational and to be used at your own risk. Two things deserve attention before you wire it into anything. The MCP debugger is a control surface with a write side, able to allocate, free, patch and call into the emulated process, and the readme describes no authentication on that endpoint, so keep it on loopback and treat anything that can reach your development machine as able to drive the emulator. And the release line is still 0.9.x, with gaps of roughly two years and a year and a half between the three listed versions, so plan to build from a commit and do not read a compatibility promise into the tag numbers.
Frequently asked questions
how to use unidbg
The readme states the scope: unidbg emulates an Android native library, plus an experimental iOS emulation, the project is educational and aimed at learning the ELF and MachO file formats and ARM assembly, and it should be used at your own risk. The workflow it documents in detail is the MCP debugger.
Which execution backends does unidbg support?
Four are named: a unicorn backend, linked as the author's own fork, which carries the console debugger, gdb stub and tracing features; dynarmic as a fast backend; the Apple M1 hypervisor, described as the fastest ARM64 backend; and a Linux KVM backend set up with a Raspberry Pi B4.
Which unidbg MCP tools can change the emulated process?
Several. The memory group includes write_memory, allocate_memory, free_memory and patch, which writes assembled instructions to memory. The registers group includes set_register, there is an assemble tool that turns instruction text into machine code, and the function call group includes call_function by address and call_symbol by module and symbol.
Does unidbg support iOS as well as Android?
It has separate iOS support: fishhook, substrate and whale hooks, the iOS Objective-C and Swift runtimes, an iOS-only MCP tool group for inspecting message sends and dumping class definitions, and a unidbg-ios module in the tree. The repository description still calls the iOS emulation experimental.
How is the unidbg MCP server exposed to an AI tool?
You type a command in the debugger console, optionally with a port, and the server starts. An SSE endpoint on localhost port 9239 is then added to the AI tool's settings. The readme describes no authentication on that endpoint and states that the project should be used at your own risk.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/zhkl0228-unidbg)Star history chart for your README
[](https://hysenlabs.com/projects/zhkl0228-unidbg)Was this useful?