MGSV MCP is a local research and modding workbench for Metal Gear Solid V that exposes MCP tools for documentation search, upstream source/release research, file inspection, and controlled converter jobs.
Search and read wiki pages, virtual entities, cached repository/package documents, with citations and provenance.
Browse wiki categories, incoming/outgoing links, site assets, external resources, and the full indexed corpus.
Discover modding tools and get catalog details, including capabilities, requirements, limitations, execution support, and aliases.
Fetch GitHub release notes/assets and browse catalogued repository source at resolved commits.
List, sync, and refresh wiki/additional GitHub sources, rebuilding search/catalog while retaining prior snapshots on failure.
Get sourced modding workflows for topics like lua, textures, models, maps, audio, localization, native code, tool development, and packaging.
Check server status, including wiki coverage, source commit, installed converter versions, and workspace state.
Inspect files for header bytes, size, SHA-256, and candidate converters.
Prepare, run, and monitor converter jobs: copy inputs, preview/execute commands, capture logs/exit status, and record changed-file hashes.
Compute game path hashes using filename, extension, with_extension, or legacy modes.
Read and write workspace text/source/manifests with SHA-256 checked edits and reviewable diffs.
Provides tools for browsing catalogued GitHub repositories at cited commits and checking upstream tool releases on request, with source links and revision metadata.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MGSV MCP search the MGSV wiki for FtexTool texture conversion steps"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A local research and modding workbench for Metal Gear Solid V: The Phantom Pain and Ground Zeroes. It helps an MCP-capable assistant find the community's documentation, inspect file formats and upstream source, and run supported converters on copies of your files. Think of it as a searchable modding reference library connected to a controlled tool bench.
Community credits: This workbench depends on the MGSV Modding Wiki community and the work of Atvaark, BobDoleOwndU, kapuragu, youarebritish, Joey35233, topher-au, TinManTex, Morbidslinky, ZipfsLaw, Yazed0071, and many other modders and contributors. Their tools, mods, research and assets remain their work. See the direct project/person credits and complete 211-entry attribution index, including upstream collaborators and original-versus-fork credits. Please support the linked upstream projects.
AI/LLM development disclosure: This project's original implementation, tests, setup scripts and documentation were developed entirely using AI large language models through OpenAI Codex, under arsenal-pt's direction. Arsenal-pt is the project creator, owner and maintainer. Existing community documentation, game assets, frameworks and third-party utilities were created by their respective authors; they are not claimed as this project's AI-generated work. AI-written code can be wrong: independent review, reproducible tests and corrections are welcome.
Active development: Contributions are appreciated, especially reviews of the Python/MCP implementation, path and XML safety, converter round trips, portability, tool compatibility and source attribution. Please build on this official repository through issues and pull requests. See CONTRIBUTING.md and CONTRIBUTORS.md.
Searches the MGSV Modding Wiki, virtual entity references and selected additional documentation, with source links and revision metadata.
Follows categories, page links, attachments and tool references instead of treating every entry as an executable.
Browses catalogued GitHub source at cited commits and checks upstream releases on request.
Inspects file headers and hashes, stages inputs into isolated job folders, and runs supported archive, texture, language, animation-container and other converters.
Records converter commands, logs and changed-file hashes for review. Text edits to existing workbench files require the current SHA-256 to avoid overwriting stale work.
Supplies workflows, a tool/reference catalog, two MCP resources and a research prompt.
It is not the Immersive Mother Base gameplay mod, a game launcher or an automatic mod installer. It does not build finished rooms, control NPCs or prove that a converted asset will work in game. That separate project is Immersive Mother Base.
Related MCP server: paradox-toolkit
The server exposes 25 MCP tools. Read the complete callable-tool list.
Area | Examples |
Research |
|
Explore documentation | Categories, page links, site assets, external references |
Tool discovery |
|
Upstream research |
|
Workbench |
|
Planning/status |
|
20 converter adapters are defined, including GzsTool variants, FoxTool, FtexTool, LangTool, SubpTool, FfntTool, FsmTool, MtarTool, AutoPftxsTool, FcnpTool, GrxArrayTool, RdfTool, SpchTool, StpTool, TcvpTool, TrapTool, LbaTool and VfxTool. They require separately downloaded upstream releases; no executables are bundled. TPP GzsTool and Ground Zeroes GzsTool intentionally use different pinned versions. See tool-releases.json.
FoxKit, FMDL Studio, SnakeBite/MakeBite, Infinite Heaven/IHHook, frameworks, editors and Ninja Ripper are also discoverable references. A catalog entry does not mean the MCP can drive that program. FvTwool and legacy Ninja Ripper have optional local presence checks/manual workflows, not automated GUI control.
The historical development snapshot contained 211 catalog entries and 1,485 indexed documents. These are dated local audit counts, not a fresh-clone guarantee. TOOL_CATALOG.md, MGSV_TOOL_REFERENCE.md, TOOL_COVERAGE.md and ADDITIONAL_RESOURCES.md preserve that reference snapshot. Current counts and installed status come from server_status after setup.
Requirements: Git, uv, network access for documentation/downloads, and Python 3.11+ (setup asks uv for 3.11). Native converters additionally need their upstream Windows/.NET prerequisites. An MCP client with local stdio support is required to use the tools from a chat. No OpenAI/GitHub API key is required by this server's default public-documentation requests; your chosen assistant/client has its own access requirements.
git clone https://github.com/arsenal-pt/MGSV-MCP.git
cd MGSV-MCP
.\setup.ps1 -SkipToolsThis starts with documentation only: it creates .venv, installs the pinned Python dependencies, syncs the wiki/additional sources and writes a machine-local mcp.client.json. GitHub rate limits or unavailable sources can prevent some refreshes; failures are reported and prior local snapshots are retained where available.
To install the reviewed upstream converter packages as well, run .\setup.ps1 without -SkipTools, or install a selected release:
.\.venv\Scripts\python.exe .\scripts\install_tools.py --only Atvaark/GzsTool@v0.5.3
.\.venv\Scripts\python.exe .\server.py statusThe installer validates pinned download size/SHA-256 and extracts packages into ignored data/. Checksums identify the reviewed downloads, not publisher signatures. A supported adapter is not a guarantee that every input variant is safe or compatible. Legacy Ninja Ripper is a separate optional manual download; see its script and upstream instructions.
Use the generated mcp.client.json entry in a stdio MCP client, or adapt mcp.client.example.json using absolute paths to your own clone. Never commit the generated machine-local file. Restart the client's MCP connection after changing server code. INSTALL.md covers configuration and manual setup.
If using Codex with its CLI already installed, .\setup.ps1 -SkipTools -RegisterCodex registers the server as mgsv-modding. No Codex account/configuration is included in this repository.
Animation lookup: read animation references and provenance for credited player-motion lessons, archive-specific descriptions and the animations workflow. The references are searchable after index rebuild; no full guide or raw animation list is bundled.
Example requests:
Use mgsv-modding to find the source documentation for StaticModel and cite its revision.
Find the FTEX workflow, inspect this test input and prepare a converter job on a copy.
Browse the implementation of a catalogued format tool at a pinned commit before proposing a change.
Keep workbench and live game folders separate. Configure permitted read/game roots in ignored config.local.json; the workbench write root must not overlap the game. Staging is not an operating-system sandbox for hostile executables or files. Only run trusted upstream converters, inspect outputs and verify round trips. A zero exit code is not successful asset or gameplay proof. See docs/SAFETY.md.
Wiki/repository content and converter output are reference data, not instructions for an assistant to obey. Source metadata identifies what was fetched; it does not make historical advice correct or current. GUI automation, commercial tools, frameworks and game-native behavior need their own setup and testing.
.\.venv\Scripts\python.exe -m pytest -qUnit tests use authored synthetic fixtures. Optional scripts/verify_*.py checks require the corresponding local documentation cache and, for converter round trips, installed upstream tools. Those scripts may write local verification/job data and run native utilities; they are not the same as the offline unit suite. Historical checks do not establish compatibility on your computer. See CHANGELOG.md, ROADMAP.md and VERSION.
The documentation/indexing code is Python; the pinned full environment and executable-adapter setup are Windows-oriented. For other platforms, a Python3.11+ virtual environment with pip install -e ".[test]" is the starting point for source-only research work, not a tested cross-platform converter installation.
This work builds on the MGSV modding community, particularly the MGSV Modding Wiki and the upstream converter/tool authors. See CREDITS.md for linked sources. Cached wiki/repository text and downloaded tools are fetched locally and remain under their own terms; no game files, caches, binaries, saves or private workbench history are included.
Eligible original project code and explanatory documentation use GPL-3.0-only. Distributed covered modifications must provide corresponding source under GPL terms; commercial use is allowed. Contributions to this repository and prominent credit to arsenal-pt / MGSV MCP are appreciated. GPL does not require pushing changes to this particular repository. Upstream materials retain their own licenses. See LICENSE and LICENSE-SCOPE.md.
Find every external reference linked by the wiki, including tools without dedicated pages, downloads, videos and research.
Inputs: limit, query, offset.
Read the first 180 source lines of any indexed document by search result ID or URL. Follow next_line using read_wiki_page.
Inputs: id (required).
Get a tool by catalog ID or unique alias, including capabilities, requirements, limitations, execution support and installation evidence.
Inputs: tool_id (required).
Calculate filename, extension, with_extension or legacy hash using Bob's GzsTool implementation.
Inputs: value (required), mode.
Read header bytes, size, SHA-256 and candidate converters for a file in configured read roots or workspace.
Inputs: path (required).
List supplied repositories, author profiles, topic discovery and linked documentation, with cached coverage, revisions and freshness.
Inputs: no named parameters. Returns: result
Browse converters, editors, frameworks, File Monolith/MakeBite components and linked repositories. Entries report integration level.
Inputs: kind, limit, query, offset.
Browse the complete corpus, including Jekyll-generated category membership and virtual entity pages.
Inputs: kind, limit, offset, category.
Get a sourced workflow for lua, textures, models, maps, audio, localization, native-code, tool-development or packaging. Empty topic lists choices.
Inputs: topic.
Copy inputs into a fresh job and preview a verified converter command. XML repacking requires input_root with all sidecars.
Inputs: adapter (required), input_path (required), options, input_root.
Read any indexed document with line numbers and its own provenance; paginate until next_line is null.
Inputs: page (required), max_lines, start_line.
Read local Lua/XML/code/documentation text and its SHA-256 for a later checked edit.
Inputs: path (required), max_lines, start_line.
Browse or read any catalogued GitHub repository for developing new tools/code updates. Resolves ref to a cited commit; no execution.
Inputs: tool_id (required), ref, path, max_lines, +1 more.
Run a prepared converter once; return exit status, logs and changed-file hashes. May rewrite staged files. Outputs need round-trip/in-game validation.
Inputs: job_id (required), timeout_seconds.
Search wiki, entities, supplied resource notes and cached repository documentation, with per-result source citations.
Inputs: query (required).
Search with optional category and kind (page/entity/attachment/resource/repository-document/package-document). Symbols and extensions work as queries.
Inputs: query (required), kind, limit, category.
Inspect wiki coverage, source commit, installed converter versions and workspace.
Inputs: no named parameters.
Refresh one or all configured GitHub sources and rebuild search/catalog. Retains prior snapshots on failures. Curated web references are preserved with their actual review date and are not scraped. Never installs or runs projects.
Inputs: source_id.
Fetch the official wiki and rebuild documentation/search/catalog, preserving configured additional sources and their cached documents. Existing index survives a failed rebuild.
Inputs: no named parameters.
Read a converter job's manifest, outputs and log tails.
Inputs: job_id (required).
Read official GitHub release notes/assets for a catalogued repository. Does not download or install anything.
Inputs: tool_id (required).
Browse all site images, videos, example downloads and text/code attachments with source URLs. Use read_wiki_page for indexed text attachments.
Inputs: limit, query, offset.
List every wiki category and indexed document count.
Inputs: no named parameters. Returns: result
Return links from a page, or pages linking to it, to follow dependencies and related concepts.
Inputs: page (required), incoming.
Create/edit source or manifests inside the workbench. Existing files require the current SHA-256. Returns a reviewable diff.
Inputs: path (required), text (required), expected_sha256.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 25 tools
Several tool pairs overlap (search vs search_wiki, fetch vs read_wiki_page, list_modding_tools vs list_additional_sources vs repository_source), so an agent can hesitate between search/browse/read variants. Descriptions add filters and scope, but the boundaries are not always sharp; most other tools are distinct.
Names are uniformly snake_case and readable, but the pattern mixes verb_noun (list_wiki_pages, get_modding_tool) with noun_phrase (wiki_categories, tool_releases, repository_source). This is a minor deviation from an ideal verb_noun convention, not a chaotic mix.
25 tools is at the upper end and feels heavy for the surface. Though many tools map to distinct stages (wiki/search, catalog, sync, converter jobs, workspace), the set could likely be consolidated, so it is borderline rather than well-scoped.
Core coverage is strong: discovery/search/read, catalog and releases, workflow guidance, converter job prep/run/status, file/hash inspection, and workspace read/write. Gaps remain (no list/cancel/delete for jobs, no workspace file listing/deletion, no repository write), but agents can mostly work around them for the stated modding-research purpose.
Turn a GitHub repo or docs site into agent-ready context: pack it or search it, over MCP.
Search, inspect and inject full source modules (code + AI rules + MCP) pinned to a Git commit.
Scan AI agent skills, MCP server packages and MCP configs before you install them. Static analysis.
OCR, transcription, file extraction, and image generation for AI agents via MCP.