Skip to main content
Glama

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

Related MCP server: Godot MCP Server Ultimate Edition

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

  1. Inspect the intended plugin, cell and reference; create a backup.

  2. Work in GECK and inspect unsaved changes in the UI.

  3. Save when a saved mod is requested; inspect any unverified save or warning.

  4. Capture exact coordinates if a file-level correction is needed.

  5. Close GECK and Fallout 3, then patch the saved reference.

  6. 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.

Available Tools

46 tools
geck_active_pluginB

Read the active plugin name from the GECK main window title.

Inputs: backend. Returns: object

geck_backup_pluginB

Copy an .esm or .esp from Data into the MCP backup directory.

Inputs: plugin_name (required), label, game_dir. Returns: object

geck_cell_find_refsB

Find references in the currently selected Cell View object list by Editor ID/Form ID/type.

Inputs: query (required), exact, column, backend, +1 more. Returns: object

geck_cell_go_to_exteriorC

Use Cell View's world-space/X/Y/Go controls to jump to an exterior cell.

Inputs: x (required), y (required), world_space (required), backend. Returns: object

geck_cell_selectC

Select an interior/exterior cell in Cell View by Editor ID.

Inputs: editor_id (required), exact, double, backend, +1 more. Returns: object

geck_cell_select_refC

Select a reference in the currently selected Cell View object list.

Inputs: query (required), exact, column, double, +1 more. Returns: object

geck_cell_set_world_spaceB

Set Cell View's world-space combo box, e.g. Interiors or Wasteland.

Inputs: world_space (required), backend. Returns: object

geck_cell_view_snapshotC

Read Cell View state: world space, selected cell, visible cells, and current cell references.

Inputs: backend, max_refs, max_cells. Returns: object

geck_click_atC

Click coordinates, window-relative by default.

Inputs: x (required), y (required), button, double, +4 more. Returns: object

geck_click_controlB

Click a child control found by title, class, UIA type, or automation id.

Inputs: title, double, handle, backend, +5 more. Returns: object

geck_control_treeB

Dump a GECK window/control tree for planning UI automation.

Inputs: handle, backend, max_depth, title_regex. Returns: object

geck_doctorC

Check paths and optional dependencies for this GECK MCP server.

Inputs: game_dir. Returns: object

geck_esp_delete_refsC

Delete placed records directly from an .esp/.esm file and update group sizes.

Inputs: ref_form_ids (required), backup, game_dir, plugin_name. Returns: object

geck_esp_delete_refs_by_baseA

Delete placed records whose NAME/base FormID matches one of the given base IDs.

Inputs: base_form_ids (required), backup, game_dir, plugin_name. Returns: object

geck_esp_list_refsA

Read placed REFR/ACHR/ACRE records from an .esp/.esm file.

Inputs: game_dir, plugin_name. Returns: object

geck_esp_nearby_refsB

Find placed records in a plugin near a coordinate.

Inputs: x (required), y (required), z (required), radius, +3 more. Returns: object

geck_esp_patch_ref_positionC

Patch a placed record with GECK closed. Rotation is in radians; omitted axes are preserved.

Inputs: x (required), y (required), z (required), ref_form_id (required), +6 more. Returns: object

geck_esp_patch_ref_to_status_barA

Legacy planning only: capture deferred patch arguments; never writes while GECK is open. Returns applied=false.

Inputs: ref_form_id (required), backup, backend, game_dir, +1 more. Returns: object

geck_esp_patch_ref_to_status_bar_offsetA

Legacy planning only: capture deferred patch arguments plus offsets; returns applied=false without writing.

Inputs: ref_form_id (required), rot_x, rot_y, rot_z, +9 more. Returns: object

geck_find_list_rowsC

Find rows in a GECK ListView by text, usually Editor ID or Form ID.

Inputs: query (required), exact, column, handle, +4 more. Returns: object

geck_focus_windowC

Focus the GECK main window or a matching dialog.

Inputs: handle, backend, title_regex. Returns: object

geck_launchA

Launch GECK normally, or with FOSE via fose_loader.exe -editor.

Inputs: game_dir, via_fose, extra_args. Returns: object

geck_list_pluginsB

List plugin files in the Fallout 3 Data folder.

Inputs: game_dir, include_bsa. Returns: object

geck_list_processesB

List GECK and FOSE-related processes.

Inputs: game_dir. Returns: object

geck_list_view_rowsC

Read rows from a Win32 ListView in a GECK window or dialog.

Inputs: handle, backend, max_rows, start_row, +3 more. Returns: object

geck_list_windowsB

List top-level desktop windows visible to pywinauto.

Inputs: backend, title_filter. Returns: object

geck_menu_selectC

Select a GECK menu path, for example File->Data... or ['File', 'Save'].

Inputs: menu_path (required), handle, backend, title_regex. Returns: object

geck_object_filterC

Set Object Window's Filter field and return the filtered rows.

Inputs: text (required), backend. Returns: object

geck_object_selectC

Select or optionally open a current Object Window record by Editor ID.

Inputs: editor_id (required), exact, double, backend. Returns: object

geck_object_snapshotC

Read the current Object Window list rows.

Inputs: backend, max_rows. Returns: object

geck_open_data_dialogC

Open GECK's File > Data dialog.

Inputs: handle, backend, title_regex. Returns: object

geck_placement_plan_from_status_barB

Dry-run a target position/rotation from GECK's status-bar coordinate plus offsets.

Inputs: rot_x, rot_y, rot_z, backend, +5 more. Returns: object

geck_placement_reportB

Assess saved placed records against the status bar, restricted to the required anchor cell_form_id.

Inputs: backend, game_dir, plugin_name, cell_form_id, +2 more. Returns: object

geck_place_object_in_renderC

Drag an Object Window record into the active Render Window to create a placed reference.

Inputs: editor_id (required), backend, dry_run, drop_x_ratio, +2 more. Returns: object

geck_plugin_statusB

Check whether an .esp/.esm exists in Data, optionally creating a backup.

Inputs: backup, game_dir, plugin_name. Returns: object

geck_read_load_orderB

Read the Fallout 3 plugins.txt load order.

Inputs: game_dir. Returns: object

geck_save_active_pluginB

Save the active GECK plugin through File > Save and return plugin status.

Inputs: backend, game_dir, wait_seconds. Returns: object

geck_screenshotC

Capture a screenshot of a GECK window or dialog as a PNG file.

Inputs: handle, backend, game_dir, file_name, +1 more. Returns: object

geck_send_keysB

Send a pywinauto key sequence to GECK, such as ^s, %{F4}, or {ENTER}.

Inputs: keys (required), focus, pause, handle, +2 more. Returns: object

geck_status_barB

Read GECK's bottom status bar, including selected object coordinates when available.

Inputs: backend. Returns: object

geck_tail_logC

Read the tail of a known GECK or FOSE log file.

Inputs: lines, game_dir, log_name. Returns: object

geck_transaction_beginA

Create a named rollback point before direct ESP/ESM file edits.

Inputs: label, game_dir, plugin_name. Returns: object

geck_transaction_listC

List recent MCP backup/transaction files, newest first.

Inputs: limit, game_dir, plugin_name. Returns: object

geck_transaction_rollbackC

Restore a plugin from a transaction id or backup path inside the MCP backup directory.

Inputs: transaction_id_or_path (required), game_dir, plugin_name, create_pre_rollback_backup. Returns: object

geck_transaction_verifyC

Verify on-disk plugin state, active GECK plugin, placed records, and recent rollback points.

Inputs: backend, game_dir, plugin_name. Returns: object

geck_write_load_orderA

Rewrite the Fallout 3 plugins.txt load order after validating plugin names.

Inputs: plugins (required), backup, game_dir. Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    C2.8/5.0

    Scored across 46 tools

    Disambiguation2/5

    Several tools have overlapping or near-duplicate purposes, such as geck_esp_patch_ref_to_status_bar and geck_esp_patch_ref_to_status_bar_offset, both legacy planning-only tools, and geck_list_view_rows/geck_find_list_rows plus geck_active_plugin/geck_plugin_status. While the set covers distinct subsystems, an agent would frequently struggle to pick the correct tool among these overlapping refs, status, and planning operations.

    Naming Consistency3/5

    Most tools follow a readable geck_ prefix with snake_case, but verb placement is inconsistent: some are verb_noun like geck_list_plugins, while others are subsystem_verb like geck_cell_select or noun phrases like geck_plugin_status, geck_status_bar, and geck_placement_report. The names remain readable, but the mixed conventions make the surface less predictable.

    Tool Count2/5

    With 46 tools, this server is well beyond the range where each tool clearly earns its place, and it includes legacy planning-only tools plus near-duplicate ref/status operations. It is not quite the 50+ extreme, but it is over-scoped and would benefit from consolidation.

    Completeness4/5

    The server covers a full placed-reference lifecycle including list, patch, delete, nearby search, and create via render, alongside plugin management, load order, transactions, UI automation, and Cell/Object window operations. Gaps like direct editing of non-reference records are minor and workable through the included UI automation tools.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      A comprehensive MCP server providing 41 tools for complete Roblox Studio control, enabling safe script editing with syntax checking, instance manipulation, and backup features directly from Claude Code or any MCP-compatible AI assistant.
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP-capable agents to locate game save files, identify their engines, compute unlock plans for gallery/recollection flags, diff saves, and safely dry-run, apply, verify, or roll back reversible byte patches with automatic backups.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables Windows 11 automation across file, document, network, host, development, shell, GitHub, shortcut, system, and guidance domains through ten canonical MCP tools. It also supports backward-compatible tool routing and persistent GitHub integration.
      MIT