mcp-azahar
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.
mcp-azahar
Unofficial MCP server and CLI for the Azahar 3DS emulator: automate testing of 3DS homebrew, locally or in CI.
Unofficial. This project is not affiliated with or endorsed by the Azahar project.
Status: v0.1.0 is released (docs/PLAN.md phases 0–8 done): CLI, MCP server, scripted tests, integration tests against Azahar in CI; binaries, container image, npm packages and the MCP Registry entry. Current status and open questions: NOTES.md. The Azahar RPC protocol as used by this tool is documented in docs/PROTOCOL.md.
What it does
One Go binary, two front ends over the same code:
a CLI for humans, shell scripts, CI and agents using bash
an MCP server (
mcp-azahar serve) for MCP clients
Both drive Azahar through its built-in RPC server: launch homebrew, send input, take screenshots, read/write memory, use save states, read logs and assert on program state. Design rationale: docs/DECISIONS.md.
Related MCP server: ryubing-mcp
Requirements
Azahar 2127.0 or newer (RPC input injection and save states). The dev container pins 2127.0-rc3.
Linux with Xvfb for headless
launch(macOS: launch on the desktop; Windows:attachonly, see NOTES.md).Go 1.27 to build from source.
Install
Container image (Linux/amd64; includes Azahar, Xvfb and Mesa, nothing else to install):
docker run -i --rm --user "$(id -u):$(id -g)" -v "$PWD:/work" ghcr.io/michvllni/mcp-azaharstarts the MCP server over stdio with your project as
/work(--userkeeps files it writes yours). A session lives as long as its container, so run several CLI commands in one container:docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/work" --entrypoint sh \ ghcr.io/michvllni/mcp-azahar -euc 'mcp-azahar launch app.3dsx --elf app.elf mcp-azahar sequence smoke.yaml; mcp-azahar stop'or keep one running (
docker run -d ... --entrypoint sleep ... infinity) and usedocker exec. Do not publish UDP port 45987 (-p) or use--network host: Azahar's RPC server is unauthenticated. Run one container per parallel session.npm (Linux, macOS, Windows; x64 and arm64; needs Node 18+):
npx -y mcp-azaharstarts the MCP server (no arguments meansserve), andnpx -y mcp-azahar <command>runs the CLI. MCP client configuration:{"command": "npx", "args": ["-y", "mcp-azahar"]}. You still need Azahar (and Xvfb for headlesslaunch) on the host.MCP Registry: published as
io.github.michvllni/mcp-azahar(npm and container packages), so registry-aware clients can install it by name.Release binaries: archives for Linux, macOS and Windows (amd64, arm64) on the releases page.
Go:
go install github.com/michvllni/mcp-azahar/cmd/mcp-azahar@latest.
CLI quickstart
go install github.com/michvllni/mcp-azahar/cmd/mcp-azahar@latest
export AZAHAR_BIN=/path/to/azahar # or put azahar in PATH
mcp-azahar launch game.3dsx # headless on its own Xvfb, waits for RPC
mcp-azahar press A # press briefly (100 ms), --for 500ms for longer
mcp-azahar hold L; mcp-azahar touch 160 120; mcp-azahar release
mcp-azahar circle-pad 154 0 --for 300ms
mcp-azahar screenshot --screen both -o shot.png
mcp-azahar read 0x00100000 16 --format dump
mcp-azahar write 0x00101000 'de ad be ef' # verified by reading back
mcp-azahar state save 1; mcp-azahar state load 1
mcp-azahar logs --tail 20 --contains Error # -f to follow, --from <offset> to resume
mcp-azahar stopSessions: every command acts on a session:
--session NAME, or$MCP_AZAHAR_SESSION, defaultdefault.sessionslists them,statusshows one, andattach --address host:portregisters an Azahar you started yourself (RPC enabled, app loaded). With Azahar 2127 only one RPC-enabled Azahar can run per host (DECISIONS.md D9).Input:
hold,touch --holdandcircle-pad --holdstay untilrelease;press, andtouch/circle-padwithout--hold, apply on top of the held input and then return to it.Output:
--jsonprints machine-readable output with stable field names; arrays are never null. It cannot be combined withread --format raw.logs -f --jsonprints one{"line": ...}object per line.--timeout 30sbounds a command;logs -falso ends when the session's emulator stops.Exit codes: 0 ok, 1 error, 2 usage error, 3 check failed, 4 no such session or emulator not running.
App output: text your homebrew passes to
svcOutputDebugStringshows up inlogs(launched sessions enable it; for attach, set[Debugging] instant_debug_log=trueand[Miscellaneous] log_filter=*:Info Debug.Emulated:Debugin Azahar's config).State files: they live in
$MCP_AZAHAR_STATE_DIR, else$XDG_STATE_HOME/mcp-azahar. A session's directory keeps Azahar's portable user dir (config, log, save states).
Scripted tests and program state
Build your homebrew with debug info (-g) and pass its ELF to launch --elf
(or attach --elf). Then read variables by name instead of by address:
mcp-azahar symbols --filter state
mcp-azahar read-symbol test_state # whole struct as JSON-like text
mcp-azahar read-symbol test_state.last_buttons --json
mcp-azahar read-symbol 0x00101000 --type s16 # raw address with a type
mcp-azahar read-symbol flags.ready # bitfields decode too
mcp-azahar read-symbol ns::counter # C++: ns::name, Class::member
mcp-azahar read-symbol update::calls # static local of update() (K::m::calls in a method)
mcp-azahar read-symbol menu.c:selected # a static whose name is used elsewhere
mcp-azahar wait-for test_state.frame 60 --op ge --timeout 5s # exit 3 on timeoutValues decode by C type: integers, floats, bools, bitfields, enums (by name),
pointers (as their address), plain char arrays as text, structs and arrays as
JSON. Only variables with a static address (globals, statics) can be read;
locals on the stack cannot.
A sequence file describes a whole test run (YAML or JSON) and works without any AI involved, e.g. in CI:
name: smoke
elf: build/app.elf # relative to this file; optional
steps:
- press: A
- press: [L, R]
for: 300ms
- hold: B
- release: all
- touch: {x: 160, y: 120}
- circle_pad: {x: 154, y: 0, for: 200ms}
- wait: 500ms
- wait_for: {target: test_state.frame, op: ge, value: 60, timeout: 5s}
- assert: {target: test_state.last_buttons, value: 0}
- assert: {target: "0x00101000", type: u32, op: ne, value: 0}
- write: {address: "0x00102000", bytes: "de ad be ef"} # memory your app does not use
- screenshot: {screen: both, output: out/smoke.png}
- save_state: 1 # waits until Azahar has written the file
- load_state: 1
- log_contains: {text: "ready", timeout: 5s}mcp-azahar sequence smoke.yaml stops at the first failing step: exit 0 if all
pass, 3 if an assert/wait_for/log_contains check fails, 2 for an invalid
file, 1 for other errors. The whole file is checked (buttons, ranges, addresses,
paths, and every target and value against the ELF) before the first step runs. --json prints a report per step with
error_kind (check or error) and duration_ms. Comparisons (op): eq, ne,
lt, le, gt, ge, and changed (no value) for wait_for; enums compare by name
or number. log_contains only matches lines logged after the run started, and
each match moves past its line.
MCP server
mcp-azahar serve speaks the Model Context Protocol over stdio. Tools only read
and write files inside the server's working directory unless you allow more
with --allow-dir (see below), so point it at your project.
Claude Code (run in your project directory; --scope project shares it via
.mcp.json):
claude mcp add azahar -- npx -y mcp-azahar # npm
claude mcp add azahar -- mcp-azahar serve # installed binary
claude mcp add azahar -- docker run -i --rm --user "$(id -u):$(id -g)" \
-v "$PWD:/work" ghcr.io/michvllni/mcp-azahar # container, Azahar includedClaude Desktop (claude_desktop_config.json: macOS
~/Library/Application Support/Claude/, Windows %APPDATA%\Claude\). Desktop
starts servers in no particular directory, so name the project:
{"mcpServers": {"azahar": {
"command": "npx",
"args": ["-y", "mcp-azahar", "serve", "--allow-dir", "/path/to/your/project"]
}}}Other clients take the same command and arguments. Agents with a shell can also
skip MCP and call the CLI directly (mcp-azahar press A --json): the commands
are the same, the output is cheaper in context, and sessions are shared, so a
human can watch or poke the instance an agent drives.
Every tool mirrors a CLI command and calls the same code, so an agent and a
human with the CLI share sessions (--session or $MCP_AZAHAR_SESSION sets
the default session; each tool also takes session):
Tool | CLI | Tool | CLI |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Durations are in milliseconds (for_ms, timeout_ms). Errors come back as
tool errors whose text starts with their kind: invalid arguments, check failed (an assert or wait that did not hold), or no running session.
azahar_sequence takes a file or an inline script; its file paths must be
relative and stay inside the sequence's directory. azahar_screenshot can also
save the PNG (output).
Files (DECISIONS.md D11): tools only read and write files (app, ELF, log,
sequence and the paths inside it, screenshot outputs) inside the server's
working directory, or the directories given with serve --allow-dir DIR
(repeatable); paths are checked after following symlinks, and dangling
symlinks are not written through. Relative paths are relative to the first
allowed directory. Results are capped to fit a model's context:
azahar_read_memory reads at most 4096 bytes, azahar_read_symbol and
azahar_wait_for values at most 16 KiB,
azahar_logs returns the last 200 lines by default (tail up to 1000),
azahar_symbols at most 500 entries (filter narrows), and screenshots use
scale 1-4 (0: Azahar's internal resolution). serve ignores --timeout.
Development
The repository ships a dev container (.devcontainer/, Debian 13 trixie)
with Go, Xvfb, Mesa software rendering, Azahar extracted to /opt/azahar,
golangci-lint, goreleaser, actionlint and shellcheck. Open the repo in it, then:
go build ./...
go test ./...
golangci-lint run ./...
go run ./cmd/mcp-azahar versionIntegration tests run the CLI against the real Azahar with a small test
homebrew, testdata/fixture (libctru; build.sh needs devkitPro, CI builds it
in the devkitpro/devkitarm image). testdata/fixture/smoke.yaml is a
complete example sequence. With the fixture in build/:
MCPAZ_FIXTURE_DIR=$PWD/build go test -tags integration -run TestFixture -v ./cmd/mcp-azahar/CI (.github/workflows/ci.yml) runs tests, linters, a cross-platform snapshot
build and the integration tests on every pull request; AGENTS.md
lists the same checks for running locally. Dependencies, actions and tool
versions are kept current by Renovate
(.github/renovate.json5).
Tool versions are pinned in .devcontainer/Dockerfile; the install scripts
in .devcontainer/ can also be run by hand (-h for help). Contributor and
agent conventions: AGENTS.md.
Releases
Releases start in the GitHub UI: after the version bump in
cmd/mcp-azahar/main.go (const version = "X.Y.Z") is merged to main,
create a new release with a new tag vX.Y.Z and publish it. The release
workflow then builds Linux, macOS and Windows binaries (amd64 and arm64)
with goreleaser and attaches them to that release, keeping its title and
notes. It fails without uploading anything if
the tag is not exactly
v+ the version inmain.go, orthe "Set as a pre-release" checkbox does not match the version (
X.Y.Z-rc.1must be a pre-release,X.Y.Zmust not).
In that case delete the release and its tag, fix the cause and publish
again. mcp-azahar version (or --version) prints the version, commit and
build date.
A release also attaches Azahar's source tarball (GPL), pushes the container
image ghcr.io/michvllni/mcp-azahar (X.Y.Z; latest only for releases),
publishes the npm packages (pre-releases under the dist-tag next) with
provenance, and finally the MCP Registry entry (releases only). Details:
AGENTS.md.
Contributing
Bug reports and feature requests use the issue forms; emulator bugs belong to Azahar. Pull requests use Conventional Commit messages and must update the docs (see AGENTS.md).
Security
Azahar's RPC server is unauthenticated and, as of Azahar 2127, always
listens on UDP port 45987 on all interfaces (not configurable). While
an Azahar started by mcp-azahar runs, anyone who can reach that port can
control the emulator: read and write memory, send input, save and load
states, take screenshots. Block the port with a firewall or run in an
isolated container, and never on an untrusted network. Because the port
is fixed, only one RPC-enabled Azahar can run per host
(DECISIONS.md D9); a configurable port and bind
address is requested upstream
(azahar-emu/azahar#2829).
The container image keeps the port inside the container's network
namespace: do not publish it (-p) or use --network host.
The MCP server treats the model's arguments as untrusted: its tools only read
and write files inside the allowed directories (serve --allow-dir, default
the working directory; DECISIONS.md D11), and results are
size-capped. Report vulnerabilities privately, see SECURITY.md.
License
GPL-3.0-or-later. See LICENSE. The container image also contains
Azahar (GPL-3.0, its source tarball is attached to each release), Qt
(LGPL-3.0) and Debian packages; see its /usr/share/doc/mcp-azahar/NOTICE.md.
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
MEOK MCP Test MCP — golden-file + schema-drift + tool-failure tests for any MCP server. Drop-in
Self-hosted MCP server: 26 deterministic dev, security, and EVM tools.
Build, test, publish and manage real MCP servers from APIs with a live developer studio.
A paid remote MCP for hosted MCP server, built to return verdicts, receipts, usage logs, and audit-r
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceControls Android emulators from any MCP-capable client via ADB and emulator CLI, supporting AVD management, APK operations, screen interactions, and device diagnostics.1-
- AlicenseAqualityDmaintenanceLocal MCP server for automating the Ryubing Nintendo Switch emulator, providing tools for controller input, touch, screenshots, logs, game launch, and session management.101MIT
- FlicenseNot gradedqualityCmaintenanceEnables MCP clients to launch and manage an owned Mindustry runtime, create logic fixtures, configure processors with mlog programs, observe live memory values, and verify program replacements with digest preconditions.7 npm1-
- AlicenseNot gradedqualityCmaintenanceEnables control of a physical Wii U over MCP, including TV/GamePad screenshots, GamePad button and stick input, calibrated touch, homebrew launch and upload, native logs, and console shell access.GPL 3.0