Skip to main content
Glama

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: attach only, 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-azahar

    starts the MCP server over stdio with your project as /work (--user keeps 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 use docker 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-azahar starts the MCP server (no arguments means serve), and npx -y mcp-azahar <command> runs the CLI. MCP client configuration: {"command": "npx", "args": ["-y", "mcp-azahar"]}. You still need Azahar (and Xvfb for headless launch) 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 stop
  • Sessions: every command acts on a session: --session NAME, or $MCP_AZAHAR_SESSION, default default. sessions lists them, status shows one, and attach --address host:port registers 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 --hold and circle-pad --hold stay until release; press, and touch/circle-pad without --hold, apply on top of the held input and then return to it.

  • Output: --json prints machine-readable output with stable field names; arrays are never null. It cannot be combined with read --format raw. logs -f --json prints one {"line": ...} object per line. --timeout 30s bounds a command; logs -f also 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 svcOutputDebugString shows up in logs (launched sessions enable it; for attach, set [Debugging] instant_debug_log=true and [Miscellaneous] log_filter=*:Info Debug.Emulated:Debug in 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 timeout

Values 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 included

Claude 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

azahar_launch

launch

azahar_screenshot (PNG image content)

screenshot

azahar_attach

attach

azahar_save_state

state save

azahar_stop

stop

azahar_load_state

state load

azahar_status

status

azahar_read_memory

read

azahar_sessions

sessions

azahar_write_memory

write

azahar_press

press

azahar_logs

logs

azahar_hold

hold

azahar_symbols

symbols

azahar_release

release

azahar_read_symbol

read-symbol

azahar_touch

touch

azahar_wait_for

wait-for

azahar_circle_pad

circle-pad

azahar_sequence

sequence

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 version

Integration 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 in main.go, or

  • the "Set as a pre-release" checkbox does not match the version (X.Y.Z-rc.1 must be a pre-release, X.Y.Z must 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…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Controls Android emulators from any MCP-capable client via ADB and emulator CLI, supporting AVD management, APK operations, screen interactions, and device diagnostics.
      1
      -
    • A
      license
      A
      quality
      D
      maintenance
      Local MCP server for automating the Ryubing Nintendo Switch emulator, providing tools for controller input, touch, screenshots, logs, game launch, and session management.
      10
      1
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables 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 npm
      1
      -