Beat Saber Modding Tools MCP
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| BEATSABER_DIR | No | Path to the Beat Saber installation, used as a fallback when the game is not auto-detected (equivalent to passing --game). | |
| BSMT_TEMPLATES_DIR | No | Directory containing the official UnityModdingTools.Templates.BeatSaber templates to use instead of the bundled copy (equivalent to --templates-dir). |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Beat Saber modding build tools for AI agents — a replacement for the BeatSaberModdingTools Visual Studio extension and BeatSaberModdingTools.Tasks.
Use this server when building or packaging a Beat Saber PC mod (BSIPA) without Visual Studio. It detects game installs, fixes BeatSaberDir, manages game references, validates/generates manifest.json, runs MSBuild or dotnet, creates BeatMods-style release zips, and deploys to Plugins (or IPA/Pending).
Recommended workflow:
detect_game— find the install and its game version.inspect_project— see references, BeatSaberDir, manifest and BSMT status.set_game_directory— write BeatSaberDir/GameDirectory if unresolved.add_game_references— add missing game DLLs (presets: core, bsipa, bsml, sira).generate_manifest— merge/fix manifest.json and embed it in the assembly. Useset_versionwhen bumping the version (manifest + AssemblyInfo together).build_modwith package=true and deploy=true — build, zip and copy to the game.
Notes:
Paths may be absolute or relative to the server's working directory.
build_modreturns ok=false with diagnostics instead of hiding build errors.When BeatSaberModdingTools.Tasks is present the server suppresses its copy/zip side effects and performs them itself, so behavior is identical whether or not the NuGet package is installed.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| detect_gameA | Detect Beat Saber installations (Steam, Oculus, BS Manager, BEATSABER_DIR) and their game versions. Pass game_dir to validate one specific install. |
| build_environmentA | Report the detected MSBuild, dotnet, git and Beat Saber installations plus setup recommendations. |
| game_process_statusA | Check whether Beat Saber.exe is currently running (deploy writes to IPA/Pending when it is). |
| inspect_projectA | Inspect a .csproj: SDK style, target frameworks, references, BeatSaberDir resolution, manifest, assembly version, BSMT.Tasks presence and git state. Use this before changing anything. |
| list_game_referencesB | List DLLs in the game's Managed/Libs/Plugins folders with versions and whether the project already references them. filter: all, managed, libs, plugins, unity, system, ipa, or a name substring. |
| add_game_referencesB | Add game DLL references to a project with HintPath rooted at $(BeatSaberDir). Use names=['Main','IPA.Loader'] or presets=['core','bsipa','bsml','sira','harmony','newtonsoft','zenject','all-managed','all-libs','all-plugins','all']. |
| remove_game_referencesC | Remove game DLL references from a project (only_game_references avoids removing framework/NuGet references). |
| set_game_directoryB | Write BeatSaberDir and GameDirectory into the project, its .csproj.user, or Directory.Build.props. target=auto updates files that already define the property and otherwise creates a .csproj.user. |
| copy_game_referencesB | Copy game Managed/Libs/Plugins DLLs into a local Refs folder (default: the parent of the project folder) and point BeatSaberDir at it. Enables offline/CI builds without the game installed. |
| add_item_templateB | Add an official item template to an existing project: harmony-patch, bsml-file, bsml-viewcontroller or monobehaviour. Creates the files and updates the .csproj (Compile/EmbeddedResource with DependentUpon). |
| list_templatesB | List project and item templates: the built-in SDK style, the official BSIPA project templates (bare, core, disableable) and the official item templates (Harmony patch, BSML file/view, MonoBehaviour). |
| create_projectB | Scaffold a BSIPA plugin project. template='sdk' (default) is an SDK-style project that builds without Visual Studio; template='bare'/'core'/'disableable' instantiates the official Visual Studio templates from UnityModdingTools.Templates.BeatSaber (vendored, or a clone via templates_dir). |
| read_manifestB | Read and validate a BSIPA manifest.json (project manifest by default). |
| generate_manifestA | Merge fields into manifest.json, validate against the BSIPA schema, write it, and (by default) make sure it is embedded as .manifest.json. Existing fields are preserved. |
| validate_manifestB | Validate a manifest.json against the BSIPA metadata schema and BSIPA dependency rules. |
| get_assembly_infoA | Read the assembly version from Properties/AssemblyInfo.cs or SDK project properties and compare it with the manifest. |
| set_versionA | Set the manifest version and the AssemblyInfo/csproj version together. Use this for version bumps: BeatSaberModdingTools.Tasks fails Release builds when the manifest and assembly versions differ. |
| compare_versionsA | Compare a manifest SemVer version with an assembly version using BSMT rules (1.2.3 == 1.2.3.0, prerelease labels ignored). |
| get_git_infoB | Return commit hash, branch, modified state, origin URL and GitHub owner for the project repository. |
| build_modB | Build a mod with dotnet (SDK-style) or MSBuild.exe (legacy). Returns diagnostics, target path and timings. Set package=true to also create the BeatMods zip and deploy=true to copy into the game. |
| package_modB | Create a BeatMods-compatible release zip from an existing build (Plugins/... at the archive root). Honors OutputCopy items; otherwise copies Plugins/.dll and .pdb. |
| deploy_modA | Copy the built mod into the game: Plugins normally, or IPA/Pending/Plugins while Beat Saber is running (BSIPA moves pending files on next launch). |
| replace_in_fileC | Replace text in a file (literal or regular expression), mirroring BSMT's ReplaceInFile task. |
| set_github_outputA | Append NAME=VALUE to a GitHub Actions output file (GITHUB_OUTPUT or output_path). |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 24 tools
The tools are mostly easy to distinguish by resource and action, but there is meaningful overlap in the environment/detection cluster (detect_game vs build_environment), the manifest cluster (read_manifest, validate_manifest, generate_manifest), and the version cluster (get_assembly_info, compare_versions, set_version). Descriptions do clarify the differences, so an agent can usually choose correctly, but the boundaries are not perfectly crisp.
The set is overwhelmingly consistent snake_case with an action-oriented verb_noun pattern such as list_game_references, add_game_references, set_version, and build_mod. game_process_status is the main exception, being noun-first rather than verb-first, but it remains clear and readable.
Twenty-four tools is on the high side, but the domain is broad: environment detection, project scaffolding, references, templates, manifests, versioning, build, packaging, deployment, and CI utilities. Most tools map to a distinct modding workflow task, so the count is slightly over typical but reasonable for this server’s scope.
The surface covers the full Beat Saber mod lifecycle: detection and environment setup, project creation and inspection, reference management, item templates, manifest validation and generation, version synchronization, build, package, deploy, and supporting CI/file utilities. There are no obvious lifecycle dead ends for the stated modding purpose.