skyrim-mcp-tools

An MCP server that lets an AI assistant read, author and maintain Skyrim Special Edition plugins (.esp). It can inspect vanilla and modded data (NPCs, quests, dialogue, Papyrus scripts, cells) and build new content: NPCs, quests, dialogue, books, items, cells and face data.

Built on esplib for plugin parsing and the Python mcp SDK (MCPServer).

Requirements

• Python 3.13

• Skyrim Special Edition (the Data folder is read for masters and scripts)

• Python packages from requirements.txt: mcp, Pillow and numpy (face painting), pytest (tests)

• esplib, bundled in esplib/ (modified copy; it requires lz4). requirements.txt installs it, or install it alone with:

pip install -e ./esplib

Related MCP server: ModWrench MCP Server

Running

python server.py

Register it in your MCP client as a stdio server running python server.py from this folder.

Configuration (environment variables)

Plugin names resolve to the output folder first, then the Data folder. Absolute paths also work. Tools that modify plugins are serialized with a lock, so batched calls are safe.

Papyrus sources and compiler

Tools that compile scripts (quest stage scripts, dialogue fragments) need the Creation Kit installed. The vanilla .psc sources in papyrus_src/ are not part of this repo (they are Bethesda's content and are git-ignored). On first compile they are extracted automatically from the CK's Data\Scripts.rar using tar, so no manual setup is needed beyond installing the Creation Kit and setting SKYRIM_CK_DIR if it is not in the default location. To prepare them ahead of time, run:

python -c "from authoring.papyrus_build import ensure_sources; print(ensure_sources())"

Supported features

Reading and search

• search_npcs, get_npc, get_npc_dialogue – find NPCs and inspect their data and dialogue

• search_quests, get_quest, get_quest_structure – quest stages, objectives, aliases, scenes, topics

• get_script – decompile .pex scripts to pseudo-source

• search_forms, search_cells, search_references, get_cell_contents, get_record

• get_npc_face, read_book, list_book_models, list_texts, list_conditions

NPC authoring

• Draft workflow: describe_npc_fields, create_npc_draft, update_npc_draft, add_npc_dialogue, get_npc_draft, validate_npc_draft, write_npc_plugin

• One-shot create_npc, and edit_npc for existing NPCs (including follower/hireling setup)

• Face shape and colour: edit_npc_face, paint_npc_face

Quest authoring

• add_quest with kinds fetch, kill, plant and radiant: add_fetch_quest, add_kill_quest, add_plant_quest, add_radiant_quest

• add_quest_alias, add_quest_stage_script, search_quests, quest_console_commands

Records, items and world

• create_record, clone_record, clone_records, edit_record

• place_item, create_cell, make_reference_persistent

• Books: edit_book (text and in-world model)

Text, conditions and scripts

• edit_text, edit_texts, lint_text, edit_condition, edit_script

Plugin lifecycle

• snapshot_plugin, list_snapshots, restore_snapshot, diff_plugin

• validate_plugin, audit_plugin

• install_plugin (copy to Data, with dry run) and package_plugin (zip)

get_weather is a placeholder tool.

Project layout

• server.py – MCP tool definitions

• tools/ – everything server.py relies on, grouped by form category: core/ (plugin model and editor shared by everything), quests/, npcs/ (including face data), dialogue/, papyrus/ (compile and decompile), books/, cells/ (cells, references, item placement), records/ (cloning, generic edits, text, snapshots)

• esplib/ – bundled, modified plugin-parsing library (MPL 2.0)

• tests/ – pytest suite

• .github/skills/ – assistant guidance for common Skyrim modding workflows

• misc/ – standalone helper scripts (graph/tree viewers, reports)

• output/ – generated plugins and sample builds

Testing

pip install -r requirements.txt
python -m pytest

GitHub Actions (tests.yml) runs only the tests that don't need game files (pytest -m "not game and not compiler"). Tests marked game need Skyrim SE (they load Skyrim.esm, about 30 s), and tests marked compiler also need the Creation Kit Papyrus compiler, so run those locally with SKYRIM_DATA_DIR and SKYRIM_CK_DIR set if your install isn't in the default Steam location:

python -m pytest -m game
python -m pytest -m compiler

Without Skyrim.esm in the Data folder, game tests are skipped automatically.

License

Licensed under the Mozilla Public License 2.0. The bundled esplib/ is a modified copy of esplib, under the same license (esplib/LICENSE).

Skyrim is a trademark of Bethesda Softworks; this project is unaffiliated.