Acpi MCP server

acpi-mcp

Let your AI agent read the firmware's ACPI tables and tell you what they mean.

<!-- mcp-name: io.github.0xmortuex/acpi-mcp -->

acpi-mcp is an MCP server that reads ACPI tables and explains them for OS developers. It covers how many CPUs there are and their APIC IDs, where the I/O APIC lives, which ISA IRQs are remapped, where the HPET and PCIe config space are, and the exact port writes that power the machine off or reset it.

It reads tables from three places:

even after the guest turns on paging);

• a live QEMU guest, out of guest physical memory through QEMU's gdbstub (works

output from any machine;

• a directory of table files: Linux's /sys/firmware/acpi/tables, or acpidump -b

• optionally, AML disassembly with iasl if you have it installed. Nothing else needs it.

Companion to qemu-mcp (boot and drive the VM) and gdbstub-mcp (debug the kernel).

What it looks like

This is real output from QEMU 11 (-M q35 -smp 2), read live from the guest:

> acpi_table MADT
MADT revision 3: local APIC base 0xfee00000 (dual 8259 PICs present: mask them before using the APIC)
  2 usable CPU(s), APIC IDs [0, 1]
  The BSP is usually APIC ID 0; start the others with INIT-SIPI-SIPI
  I/O APIC id 0 at 0xfec00000, GSI base 0
  Interrupt source overrides (legacy ISA IRQ -> GSI):
    IRQ0 -> GSI 2 (I/O APIC 0 pin 2), bus default, bus default - this is why the PIT timer shows up on I/O APIC pin 2, not 0
    IRQ9 -> GSI 9 (I/O APIC 0 pin 9), active high, level - non-ISA polarity/trigger: program the redirection entry to match
    ...
  Local APIC NMI on LINT1 for all CPUs (bus default, bus default) - program LVT LINT1 as NMI

> acpi_find "how do I shut down the machine?"
Soft power-off (S5): \_S5_ = SLP_TYPa 0, SLP_TYPb 0
  1. If SMI_CMD (0xb2) is non-zero and SCI_EN (bit 0 of PM1a_CNT) is clear, enable ACPI: outb(0xb2, 0x2) and wait for SCI_EN
  2. outw(0x604, 0x2000)   # SLP_TYPa << 10 | SLP_EN (bit 13)

> acpi_find "reboot"
Reset: write 0xf to I/O port 0xcf9 (8-bit) (FADT RESET_REG, RESET_REG_SUP set). Fall back to the 8042 if it returns.

> acpi_find "pci config space"
MCFG: PCI Express ECAM (memory-mapped config space)
  segment 0, buses 0-

The recipes are tested, not just printed. The integration tests write the exact instructions acpi_find prescribes into a live guest, run them, and check the result: the shutdown recipe powers off both -M pc and -M q35, and the reset recipe resets q35. A control case that only runs hlt keeps running.

Why

ACPI is the first wall every hobby OS hits after "hello world". You need it for SMP, the I/O APIC, the HPET, PCIe and power-off. The tables are binary structures spread across firmware memory, the spec runs to over a thousand pages, and the bugs are silent: miss the IRQ0 → GSI2 override and your timer simply never fires. This server reads the tables your firmware actually built and answers in terms of what to program.

As far as I could find, no other MCP server reads or explains ACPI tables.

Install

pip install acpi-mcp
claude mcp add acpi -- acpi-mcp

Usage

Start QEMU with its gdbstub (-s). -S is fine, because acpi-mcp lets the firmware run until the tables exist:

qemu-system-x86_64 -M q35 -smp 2 -kernel kernel.elf -s -S

Shortened. The full README is on GitHub.