F4 Crash Doctor

Advisory-only Fallout 4 crash diagnosis for Claude Desktop, Claude Code, or any MCP client.

When your modded Fallout 4 crashes, this tool reads the crash log, your load order, and your game setup, then explains the likely cause and fix in plain English — right inside your Claude conversation.

It is an MCP server — MCP (Model Context Protocol) is the standard way to give an AI assistant like Claude safe, well-defined abilities on your PC. This one gives Claude the ability to read your Fallout 4 crash information, nothing more.

Safety promise

This tool never writes, moves, deletes, or modifies any file. Ever.

It has zero tools capable of changing anything — every tool it exposes is read-only. It only looks at your crash logs, your plugin list, and your game folder, then tells you what it found.

Because it never touches your install, it works safely alongside Vortex or Mod Organizer 2. It even detects which mod manager you use, so the advice you get is phrased for your setup (e.g. "disable this in Vortex" vs "untick it in MO2's left pane").

What you need

• Windows 10 or 11

• Fallout 4 (Steam) with:

  • F4SE (Fallout 4 Script Extender — a loader many mods require, run via f4se_loader.exe)
  • Buffout 4 — the mod that actually writes crash logs when the game crashes. Without it there is nothing to diagnose. Get it here: https://www.nexusmods.com/fallout4/mods/47359

• uv — a small free tool that runs Python programs without any setup on your part. One-line install in PowerShell:

  winget install astral-sh.uv
  

  or, if winget isn't available:

  irm https://astral.sh/uv/install.ps1 | iex
  

You do not need to install Python yourself — uv handles it.

Install

Easiest: the one-file bundle (Claude Desktop)

Download f4-crash-doctor.mcpb from the latest release — on the release page, click the small Assets row under the notes to expand it; the .mcpb file is listed there (not in the release text itself). Then in Claude Desktop open Settings → Extensions → Advanced settings and click Install Extension… — pick the downloaded file. (Drag-and-dropping the file onto the Extensions page works on some machines, but Windows refuses the drop with a 🚫 cursor when it doesn't know the .mcpb file type — the Install Extension… button works everywhere.) Claude Desktop asks two optional questions (game folder — leave empty to auto-detect; Nexus API key — skip unless you want mod lookups), and you're done. Skip straight to First use below.

Updating from an older version: don't install over the top — Windows locks the running version's files and the install fails (EBUSY). Instead: Settings → Extensions → remove the old F4 Crash Doctor → Install Extension… with the new file → then fully restart Claude Desktop (quit from the system-tray icon, not just the window) so the new server starts. Start a new conversation after updating — an old chat will keep reasoning from the old version's answers.

Manual install (Claude Code, other MCP clients, or if you prefer a terminal)

1. Download or clone this repository somewhere permanent, e.g. C:\Tools\f4-crash-doctor.

2. Open a terminal (PowerShell) in that folder.

3. Run:

   uv sync
   

   This downloads the few libraries the tool needs. It takes a few seconds and only needs to be done once.

Hook it up to Claude Desktop

1. Open your Claude Desktop config file. It lives at:

   %APPDATA%\Claude\claude_desktop_config.json
   

   (Paste that path into the File Explorer address bar. If the file doesn't exist, create it.)

2. Add this block (or merge f4-crash-doctor into an existing mcpServers section):

   {
     "mcpServers": {
       "f4-crash-doctor": {
         "command": "uv",
         "args": ["run", "--directory", "C:\\path\\to\\f4-crash-doctor", "f4-crash-doctor"]
       }
     }
   }
   

   Replace C:\\path\\to\\f4-crash-doctor with the real path to this folder, keeping the double backslashes (e.g. C:\\Tools\\f4-crash-doctor).

   If the server never shows up in Claude (the most common setup hiccup): Claude Desktop may not find uv right after you install it, because the updated PATH hasn't reached Claude yet. The reliable fix is to use the full path to uv.exe as the command instead of just "uv":

   "command": "C:\\Users\\<your-username>\\.local\\bin\\uv.exe"
   

   (That's where both installers put it. To confirm, run where.exe uv in PowerShell.) Alternatively, sign out of Windows and back in — or reboot — so the new PATH reaches every program, and keep "command": "uv".

3. Restart Claude Desktop (fully quit from the system tray, then reopen).

Hook it up to Claude Code

One command:

claude mcp add f4-crash-doctor -- uv run --directory C:\path\to\f4-crash-doctor f4-crash-doctor

Again, replace the path with the real location of this folder.

First use

After your next crash, just ask:

"Diagnose my last Fallout 4 crash."

Claude should call scan_game_environment and diagnose_crash and walk you through what happened and what to do about it.

For a guided, step-by-step diagnosis workflow, use the built-in prompt diagnose-fallout4-crash (in Claude Desktop it appears in the prompts/attachments menu once the server is connected).

Optional: Nexus Mods lookups

Two tools (lookup_mod and check_nexus_auth) can fetch mod info from Nexus Mods, which needs a free personal API key:

1. Get your key from nexusmods.com → your avatar → Settings → API Keys.
2. Provide it one of two ways:

   • Create a file named .env in the repository folder containing:

     NEXUS_API_KEY=your-key-here
     

   • Or add it to the Claude Desktop JSON block:

     "f4-crash-doctor": {
       "command": "uv",
       "args": ["run", "--directory", "C:\\path\\to\\f4-crash-doctor", "f4-crash-doctor"],
       "env": { "NEXUS_API_KEY": "your-key-here" }
     }
     

Everything else works without a key — only the two Nexus tools need it.

The tools (all read-only)

Tool	What it does
list_crash_logs	Lists your Buffout 4 crash logs, newest first
get_crash_log	Reads and parses one crash log (newest by default)
get_load_order	Reads your plugin load order and cross-checks it against your Data folder
scan_game_environment	Checks game version, F4SE, Buffout 4, Address Library, and which mod manager you use
diagnose_crash	The full pipeline: parses the log, scans your setup, and matches known crash signatures
lookup_mod	Looks up a mod on Nexus Mods (needs API key)
check_nexus_auth	Confirms your Nexus API key works (needs API key)

Troubleshooting

• Dragging the .mcpb onto Extensions shows a 🚫 no-drop cursor — your Windows has no .mcpb file association, so the drop (and double-clicking the file) has nowhere to go. Use Settings → Extensions → Advanced settings → Install Extension… instead — it always works.
• The server doesn't appear in Claude / never connects — almost always Claude Desktop failing to find uv. Use the full path to uv.exe as the "command" (see the note in the install section above: usually C:\\Users\\<your-username>\\.local\\bin\\uv.exe), or sign out of Windows and back in so the freshly installed uv is on every program's PATH. Also double-check the config file is valid JSON (a missing comma is enough to break it) and that you fully quit Claude Desktop from the system tray before reopening.
• "No crash logs found" — Buffout 4 hasn't logged a crash yet. The folder Documents\My Games\Fallout4\F4SE\Crash Logs is only created the first time the game actually crashes with Buffout 4 installed. If the game has crashed but there's still no log, double-check Buffout 4 is installed and loading.
• OneDrive moved my Documents folder — handled automatically; the tool asks Windows where your real Documents folder is. If it still looks in the wrong place, set the environment variable F4_DOCS_DIR to your Documents path (the one containing My Games).
• Game installed somewhere unusual — the tool finds Steam libraries automatically, but if your Fallout 4 lives somewhere it can't find, set F4_GAME_ROOT to the folder containing Fallout4.exe.

For developers

uv sync          # install dependencies (note: needs src/f4_crash_doctor present; harmless to re-run)
uv run pytest    # run the test suite

Source layout: src/f4_crash_doctor/ (package), tests/ (pytest), src/f4_crash_doctor/data/ (signature knowledge pack, calibration profile, prompt kit — data, not code), packaging/ (MCPB bundle build — uv run python packaging/build_mcpb.py).