What is this?

GECK MCP connects an AI assistant to the local Garden of Eden Creation Kit for Fallout 3. The skill teaches the assistant the workflow; the MCP server supplies the tools. You need both to use the complete Codex workflow.

The server uses Windows UI Automation and bounded plugin-file operations. It runs locally over stdio and does not include an AI model, game assets, GECK, or FOSE. Other MCP clients can use the server; the bundled instructions are written for Codex.

Your request → Codex + geck-mcp skill → local MCP server
                                        ├─ GECK windows, menus and controls
                                        └─ plugin inspection, backups and edits

What you can do

Workflow	Available capabilities
Diagnose	Check paths and dependencies; inspect processes, windows and logs
Navigate	Find cells by Editor ID; jump to exterior coordinates; inspect Cell View
Work with objects	Filter Object Window; find/select refs; drag objects into Render Window
Inspect the editor	Read controls, lists and status bar; capture screenshots
Manage plugins	List plugins; inspect load order; back up, restore and verify disk state
Correct placement	Read REFR/ACHR/ACRE; change position and rotation with GECK closed
Check results	Scope distance checks to a cell; verify supported file structure

See the complete tool reference for all 46 tools and their boundaries.

Quick setup

1. Install the server

Use Windows, Git, Python 3.11+, an installed copy of Fallout 3, and GECK for Fallout 3. FOSE is optional unless you need its editor/script support. Run UI automation in your interactive Windows desktop session.

In PowerShell:

git clone https://github.com/maksimka2432fr23/codex-skill-mcp-fallout3.git
cd codex-skill-mcp-fallout3
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .

If your Python installation has no py launcher, use python -m venv .venv.

2. Connect Codex

Merge examples/codex-config.toml into your Codex ~/.codex/config.toml. Replace the repository and game paths with your own. Do not replace the rest of your configuration.

[mcp_servers.geck]
command = 'C:\Tools\codex-skill-mcp-fallout3\.venv\Scripts\python.exe'
args = ["-m", "geck_mcp"]
cwd = 'C:\Tools\codex-skill-mcp-fallout3'

[mcp_servers.geck.env]
GECK_MCP_FALLOUT3_DIR = 'C:\Games\Fallout 3 goty'

This is a stdio server: the MCP client launches it. No port or server API key is required. Your AI client may have its own account and billing requirements. Configuration follows the official Codex MCP documentation.

3. Install the skill

From the cloned repository, copy the skill into your user skill directory:

$skillRoot = Join-Path $env:USERPROFILE '.agents\skills'
New-Item -ItemType Directory -Force -Path $skillRoot | Out-Null
Copy-Item -LiteralPath '.\skills\geck-mcp' -Destination $skillRoot -Recurse

If geck-mcp already exists there, review and update that copy instead of creating duplicates. Alternatively, ask Codex's $skill-installer to install skills/geck-mcp from this repository. The server still needs steps 1–2. See official skill discovery and installation guidance.

Restart/reconnect Codex's MCP session after setup or server updates.

4. Check the connection

Ask Codex:

Use $geck-mcp to run geck_doctor and inspect whether GECK is running. Do not modify any plugins.

The diagnostic should find your GECK executable, Data folder and required Python dependencies. A missing FOSE loader is expected if you have not installed FOSE.

Try these prompts

Launch GECK through FOSE and inspect its main window.

Open MegatonMoriartysSaloon and show the references in Cell View.

Back up MyMod.esp and list its saved placed objects.

Plan a placement from the selected anchor with a Z offset of -8. Show the coordinates before changing anything.

Explain the recent warnings in EditorWarnings.txt.

Object selection uses the current Object Window category. A prompt is an example workflow, not a guarantee that the requested record exists in every installation.

A reliable editing loop

Inspect the intended plugin, cell and reference; create a backup.
Work in GECK and inspect unsaved changes in the UI.
Save when a saved mod is requested; inspect any unverified save or warning.
Capture exact coordinates if a file-level correction is needed.
Close GECK and Fallout 3, then patch the saved reference.
Verify and reopen for visual checks; roll back if the result is wrong.

Direct edits use a verified temporary file, atomic replacement and a check for intervening changes. Omitted rotation axes are preserved; explicit file rotations are in radians. Distance reports require the anchor's cell_form_id.

Limitations

Experimental UI automation. Window layouts, localization, modal dialogs and privileges can affect control discovery. Live UI workflows need testing on your installation.
No native GECK API. This does not expose the editor's internal object model or guarantee automatic quest, script, dialogue or navmesh authoring.
Bounded ESP support. Direct placement editing targets REFR, ACHR and ACRE. Compressed placed records and extended XXXX subrecords are rejected. NAVM is out of scope.
Disk and UI are different states. Unsaved objects are absent from file reads. Direct edits and rollback are blocked while GECK/FOSE or a process in the game directory is running.
Legacy status-bar patch tools only plan. They return applied=false and deferred arguments; apply those after closing the editor.
Coordinates are not collision checks. Object origin, bounds and floor contact still need visual/game validation. IDs from the UI may use different load-order prefixes from on-disk IDs.
Deletion is file-local. Removing an override is not the same as deleting its master object. This is not a full dependency/link validator.
Local execution is not an offline AI guarantee. Tool results and screenshots can be sent to your configured AI client/provider. The server itself does not call an AI API.

Configuration

Environment variable	Purpose
`GECK_MCP_FALLOUT3_DIR`	Your game installation; set explicitly
`FALLOUT3_DIR`	Fallback game-directory variable
`GECK_MCP_GECK_EXE`	Override the GECK executable path
`GECK_MCP_DATA_DIR`	Override the Data directory
`GECK_MCP_LOAD_ORDER_FILE`	Override plugins.txt, e.g. for a mod-manager profile
`GECK_MCP_BACKUP_DIR`	Backup location; defaults to `backups/` under server cwd
`GECK_MCP_SCREENSHOT_DIR`	Screenshot location; defaults to `screenshots/` under server cwd

Without an explicit game path the server tries the conventional Steam directory under Program Files (x86). Without a load-order override it uses %LOCALAPPDATA%\Fallout3\plugins.txt. Mod-manager virtual filesystems are not automatically detected; configure the visible paths and inspect them with doctor.

Development and verification

.\.venv\Scripts\python.exe -m unittest discover -s tests -v

The initial editing suite covers 19 cases, including malformed containers, rotation preservation, failed writes, concurrent file changes, cell scoping, rollback and mocked save dialogs. Tests create synthetic plugins in temporary directories; GECK and Fallout 3 are not required. CI runs these checks on Windows.

On the development machine, structural traversal was also checked against nine installed ESP files without changing them. This is not evidence of compatibility with every plugin or a full end-to-end GECK UI test.

skills/geck-mcp/   Codex workflow instructions
src/geck_mcp/      Local stdio MCP server and bounded ESP parser
tests/            Synthetic plugin and configuration tests
examples/         Portable Codex configuration
docs/             Russian guide, banner and tool reference

Contributing

Bug reports and focused pull requests are welcome. Include the tool name, error, Windows/Python/GECK versions and a minimal reproduction. For parser changes, add a synthetic regression test. For UI changes, describe the editor state and how you verified it. Do not attach copyrighted game files or personal logs.

Potential next steps: broader parser coverage, stronger UI identification, more placement checks, and dedicated quest/script workflows.

License and credits

MIT. Community project by maksimka2432fr23. Not affiliated with or endorsed by Bethesda or OpenAI. Fallout and GECK belong to their respective owners; no game files are distributed here.

Built with MCP Python SDK, pywinauto, psutil and Pillow. Format reference: xEdit's Fallout 3 record documentation.

GECK MCP