Skip to main content
Glama
boot-doctor-mcp

boot-doctor-mcp

by pamela-0

boot-doctor-mcp

PyPI License: MIT

A real MCP server for PC no-boot / no-display / no-POST troubleshooting. No LLM guessing at hardware causes — a plain, deterministic rule engine plus real, sourced BIOS beep-code tables.

Why deterministic, not an LLM

Nobody wants a language model hallucinating "your GPU is dead" when it isn't. Hardware advice where being wrong costs real money and real time deserves a fixed, auditable rule set, not a plausible-sounding guess. Every answer this tool gives traces back to a real source or a fixed, testable rule — never an invented explanation.

Related MCP server: SentinelMCP

Tools

diagnose_symptoms(powers_on, fans_spin=None, fans_stay_running=None, display_output=False, tried_cmos_reset=False, tried_minimal_config=False, tried_different_cable_or_monitor=False)

Real, ranked next troubleshooting steps, given what's already been tried — the same power-stage → CMOS reset → minimal-config-test → swap-test sequence a real technician runs, ordered by what's cheapest to rule out first. Not a diagnosis of the exact broken part; a real repair often still needs a swap test against known-good parts, and this tool says so explicitly rather than pretending symptom-matching alone can replace it.

lookup_beep_code(bios_type, pattern)

Looks up a beep pattern (e.g. "10 short", "1 long, 2 short", "continuous") against real, sourced BIOS beep-code tables.

bios_type is one of:

  • ami_legacy — classic AMIBIOS

  • ami_aptio — modern AMI Aptio (UEFI), kept separate on purpose: legacy AMIBIOS and Aptio use genuinely different codes for the same beep counts, a mistake common in beginner troubleshooting guides that merge them into one table

  • award_phoenix — Award/Phoenix BIOS

Returns real information, not a fabricated guess, when the exact pattern isn't in the table — modern boards increasingly have no speaker at all and use debug LEDs instead, so "no match" is itself a real, honest result.

Sources

Beep-code data fetched and cross-referenced live (not from training-data memory) from IONOS and Thomas-Krenn. Real, stated limitation: OEMs (HP, Dell, ASUS, etc.) sometimes customize or extend these codes, and modern boards increasingly skip the speaker entirely in favor of debug LEDs — a documented pattern not matching here doesn't necessarily mean nothing is wrong.

Install

pip install boot-doctor-mcp

Add to your MCP client config (e.g. Claude Code):

claude mcp add boot-doctor-mcp -- boot-doctor-mcp

Or run directly for local testing:

python -m boot_doctor_mcp.server

Skill

A SKILL.md ships inside this same package — not a separate download — and teaches Claude when and how to use these tools correctly (e.g. never guessing a BIOS type, never stating a broken component as fact from symptoms alone). Install it into your project:

boot-doctor-mcp-install-skill

Run it from the project root you want the skill active in — it writes to .claude/skills/boot-doctor-mcp/SKILL.md relative to your current directory.

Development

pip install -e ".[dev]"
pytest

Available Tools

2 tools
diagnose_symptomsA

Real, ranked next troubleshooting steps for a PC that won't boot or show any display, given what's already been tried. Not a diagnosis of the exact broken part — a real technician's standard sequence, ordered by what's cheapest/fastest to rule out first.

powers_on: does ANYTHING happen when you press the power button (any light, any fan movement, any sound) — false means dead/no-power, a completely different problem class than a POST failure. fans_spin: do the fans spin at all when powered on. fans_stay_running: do they keep spinning, or spin briefly then stop (the latter is a real, specific PSU/motherboard protection signal). display_output: is there ANY video signal reaching the monitor. tried_cmos_reset: already removed the CMOS battery / used the CLR_CMOS jumper. tried_minimal_config: already stripped to CPU + 1 RAM stick + no discrete GPU (or GPU alone) to isolate the cause. tried_different_cable_or_monitor: already confirmed the monitor and cable work on a different, known-good computer.

Inputs: powers_on (required), fans_spin, display_output, tried_cmos_reset, +3 more. Returns: result

lookup_beep_codeA

Looks up a beep pattern against real, sourced BIOS beep-code tables. bios_type must be one of: ami_legacy, ami_aptio, award_phoenix — ami_legacy and ami_aptio are genuinely different tables (legacy AMIBIOS vs. modern AMI Aptio/UEFI use different codes for the same beep counts), pick the wrong one and you'll get the wrong answer, so check which BIOS the actual board uses before trusting the result.

pattern: free text describing what you heard, e.g. "10 short", "1 long, 2 short", "continuous", "3 short, 3 long, 3 short".

Returns None-equivalent text (not a fabricated guess) when the exact pattern isn't in the real table this tool has data for — modern boards increasingly have no speaker at all and use debug LEDs instead, so no match is real information, not a tool failure.

Inputs: pattern (required), bios_type (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools serve completely different purposes: diagnose_symptoms walks through a troubleshooting decision tree, while lookup_beep_code is a reference lookup. There's zero overlap or ambiguity about which to call in any scenario.

    Naming Consistency5/5

    Both tools follow the identical imperative verb_noun snake_case convention (diagnose_symptoms, lookup_beep_code). Perfect consistency, even if the sample size is small.

    Tool Count3/5

    Two tools is on the thin side for a general-purpose troubleshooting server, but the scope here is deliberately narrow (diagnosis guidance + beep-code reference). It works, but feels minimal.

    Completeness3/5

    The core workflows (symptom-based guidance and beep-code lookup) are covered, but natural additions like a debug-LED/literal code reference, or a POST-code table, would round out the domain. Notable but not critical gaps.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      Enables LLM-driven agents to autonomously detect, diagnose, repair, verify, and prevent software and hardware failures on local and remote systems. Includes built-in safety checks and automatic rollbacks.
      15
      -
    • A
      license
      A
      quality
      D
      maintenance
      Expert system hardware probe and performance diagnostic engine for AI, Gaming, and High-Performance workflows. Provides deep system insights such as real-time monitoring, thermal diagnostics, and LLM optimization.
      11
      57 npm
      7
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to diagnose broken XAMPP/WAMP localhost stacks by inspecting real machine state — running processes, listening ports, HTTP probes, and Apache/MySQL error logs — to pinpoint port conflicts, startup crashes, unclean-shutdown damage, and zombie processes with plain-English explanations. All diagnostics are read-only, so agents can safely answer questions like why Apache won't start or why localhost refuses to connect instead of guessing.
      4
      MIT