Beat Saber Modding Tools MCP

An MCP server and CLI that replace the BeatSaberModdingTools Visual Studio extension and BeatSaberModdingTools.Tasks MSBuild tasks when you build Beat Saber PC mods with an AI agent instead of Visual Studio.

The server detects the game, fixes BeatSaberDir, manages game references, validates and embeds manifest.json, runs MSBuild/dotnet, creates BeatMods-style release zips, and deploys the plugin to Plugins (or IPA/Pending while the game is running).

• Python 3.10+

• Windows (game detection, BSIPA deployment)

• No Visual Studio required: use Visual Studio Build Tools or the .NET SDK (dotnet)

• Works with existing BSIPA projects that use BeatSaberModdingTools.Tasks

uvx --from git+https://github.com/denpadokei/BeatSaberModdingToolsMCP bsmt-mcp

これは何か（日本語）

このリポジトリは、Beat Saber の PC Mod（BSIPA）を Visual Studio なしで開発・ビルドするための MCP サーバーです。BeatSaberModdingTools（Visual Studio 拡張機能）と BeatSaberModdingTools.Tasks（MSBuild タスク）の主要機能を Python で再実装し、 GitHub Copilot / Claude / Codex などの MCP クライアントや CLI から利用できます。

できること

• Steam / Oculus / BS Manager のゲーム検出、BeatSaberDir / GameDirectory の設定

• ゲーム DLL 参照の追加・削除、オフラインビルド用の Refs コピー

• manifest.json の生成・検証・アセンブリへの埋め込み、AssemblyInfo とのバージョン同期

• dotnet / MSBuild でのビルド、BeatMods 形式 zip の作成、Plugins / IPA/Pending への配置

• 公式プロジェクトテンプレート（bare / core / disableable）

• 公式アイテムテンプレート（Harmony / BSML / BSML ViewController / MonoBehaviour）

• 24 個の MCP ツールと bsmt CLI

すぐ使う

# セットアップ確認（ゲーム・MSBuild・dotnet・git）
uvx --from git+https://github.com/denpadokei/BeatSaberModdingToolsMCP bsmt doctor

# MCP サーバーを単体で起動する場合
uvx --from git+https://github.com/denpadokei/BeatSaberModdingToolsMCP bsmt-mcp

MCP クライアント設定（汎用）:

{
  "mcpServers": {
    "beatSaberModdingTools": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/denpadokei/BeatSaberModdingToolsMCP",
        "bsmt-mcp"
      ]
    }
  }
}

GitHub Copilot の設定は GitHub Copilot での使い方 を参照してください。

基本的な流れ

1. detect_game — ゲームのインストールを検出

2. inspect_project — 参照・BeatSaberDir・manifest の状態を確認

3. set_game_directory — BeatSaberDir / GameDirectory を設定

4. add_game_references — 不足しているゲーム DLL を追加

5. generate_manifest / set_version — manifest とバージョンを整備

6. build_mod(package=true, deploy=true) — ビルド、zip 作成、ゲームへ配置

テンプレート

# プロジェクト作成（SDK スタイル / 公式テンプレート）
uvx --from git+https://github.com/denpadokei/BeatSaberModdingToolsMCP bsmt create .\MyMod --name "My Mod"
uvx --from git+https://github.com/denpadokei/BeatSaberModdingToolsMCP bsmt create .\MyMod --template core --game "D:\...\Beat Saber"

# アイテム追加
uvx --from git+https://github.com/denpadokei/BeatSaberModdingToolsMCP bsmt item add .\MyMod --template harmony-patch --name MyPatch --directory Patches
uvx --from git+https://github.com/denpadokei/BeatSaberModdingToolsMCP bsmt item add .\MyMod --template bsml-viewcontroller --name SettingsView --directory UI

詳細なツール一覧・CLI・トラブルシューティングは以下の英語セクションに記載しています。

Related MCP server: mcp-server-unity

Quick start (MCP client)

Add the server to your MCP client configuration. The exact wrapper key depends on the client (mcpServers for Claude Desktop/Codex-style clients, context_servers, etc.); the command is always the same.

{
  "mcpServers": {
    "beat-saber-modding-tools": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/denpadokei/BeatSaberModdingToolsMCP",
        "bsmt-mcp"
      ]
    }
  }
}

The first launch clones the repository, builds the wheel, and caches it. Later launches are fast.

GitHub Copilot での使い方

VS Code（Copilot Chat）と GitHub Copilot CLI の両方に対応しています。

VS Code — %APPDATA%\Code\User\mcp.json（Windows）の servers に追加:

{
  "servers": {
    "beatSaberModdingTools": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/denpadokei/BeatSaberModdingToolsMCP",
        "bsmt-mcp"
      ]
    }
  }
}

追加後、VS Code で Developer: Reload Window を実行し、コマンドパレットの MCP: List Servers から beatSaberModdingTools を開始・承認してください。

GitHub Copilot CLI — ~/.copilot/mcp-config.json の mcpServers に追加:

{
  "mcpServers": {
    "beatSaberModdingTools": {
      "type": "local",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/denpadokei/BeatSaberModdingToolsMCP",
        "bsmt-mcp"
      ],
      "tools": ["*"],
      "timeout": 900000
    }
  }
}

CLI では次のコマンドでも追加できます:

copilot mcp add beatSaberModdingTools --timeout 900000 -- uvx --from "git+https://github.com/denpadokei/BeatSaberModdingToolsMCP" bsmt-mcp
copilot mcp list

timeout はビルドやパッケージ作成に余裕を持たせるため 15 分にしています。 Copilot からは「この Mod を Release でビルドして zip を作って」のように依頼すると、 inspect_project → build_mod などのツールが使われます。

uvx run git+<url>

uvx takes the package with --from and the command as the following argument, so the literal form uvx run git+<url> would ask uvx for a PyPI package named run. To keep the command shape short, this package installs a run alias equivalent to bsmt-mcp:

uvx --from git+https://github.com/denpadokei/BeatSaberModdingToolsMCP run
uvx --from git+https://github.com/denpadokei/BeatSaberModdingToolsMCP bsmt-mcp   # same server

For a local checkout:

uvx --from "git+file:///C:/path/to/BeatSaberModdingToolsMCP" bsmt-mcp

CLI quick start

The same code is available as the bsmt command, which is handy from a terminal or from an agent that can run commands but not MCP.

# 1. Find the game
uvx --from git+https://github.com/denpadokei/BeatSaberModdingToolsMCP bsmt detect

# 2. Inspect a project
uvx --from git+https://github.com/denpadokei/BeatSaberModdingToolsMCP bsmt inspect .\MyMod

# 3. Point the project at a game install
uvx --from git+https://github.com/denpadokei/BeatSaberModdingToolsMCP bsmt setup .\MyMod --target user

# 4. Add references (presets: core, bsipa, bsml, sira, harmony, newtonsoft, zenject)
uvx --from git+https://github.com/denpadokei/BeatSaberModdingToolsMCP bsmt refs add .\MyMod --preset core --preset bsipa

# 5. Build, zip and deploy
uvx --from git+https://github.com/denpadokei/BeatSaberModdingToolsMCP bsmt build .\MyMod -c Release --package --deploy

# 6. Scaffold a new project
uvx --from git+https://github.com/denpadokei/BeatSaberModdingToolsMCP bsmt create .\NewMod --name "New Mod"

After the first uvx run you can also install it once:

uv tool install git+https://github.com/denpadokei/BeatSaberModdingToolsMCP
bsmt doctor

What it replaces

The behavior is modeled on:

• Zingabopp/BeatSaberModdingTools

• Zingabopp/BeatSaberModdingTools.Tasks

• denpadokei/BeatSaberModdingTools (fork with fixes; the detection code follows the fixed behavior)

Build behavior

• SDK-style projects build with dotnet build when available, otherwise MSBuild.

• Legacy (non-SDK) projects build with MSBuild.exe from Visual Studio or Build Tools.

• When BeatSaberModdingTools.Tasks is present, the build passes DisableCopyToGame=true, DisableCopyToPlugins=true and DisableZipRelease=true so the package does not duplicate the server's packaging/deploy. Manifest generation by the package still works.

• package_mod honors OutputCopy items and otherwise copies Plugins/<AssemblyName>.dll (+ PDB). The zip contains Plugins/... at its root, exactly like BSMT_ZipRelease. Pass include_manifest=true if your distribution needs a root manifest.json too.

• deploy_mod writes to Plugins normally and to IPA/Pending while Beat Saber.exe is running, matching BSIPA's pending-file mechanism.

MCP tools

Read-only tools: detect_game, build_environment, game_process_status, inspect_project, list_game_references, read_manifest, validate_manifest, get_assembly_info, compare_versions, get_git_info, list_templates.

Mutating tools: add_game_references, remove_game_references, set_game_directory, copy_game_references, create_project, add_item_template, generate_manifest, set_version, build_mod, package_mod, deploy_mod, replace_in_file, set_github_output.

Recommended workflow

1. detect_game — choose the install (the newest or the BS Manager last-launched instance).

2. inspect_project — see whether references, BeatSaberDir, and the manifest are sane.

3. set_game_directory — write BeatSaberDir/GameDirectory if the project does not resolve them.

4. add_game_references — add missing DLLs; start with presets=["core","bsipa"].

5. generate_manifest — merge fields, validate, and embed the manifest. Use set_version when bumping the version so the manifest and AssemblyInfo.cs stay in sync.

6. build_mod with package=true and deploy=true.

Agents should check ok in the returned JSON. build_mod returns ok=false with parsed diagnostics instead of hiding compiler errors.

Templates

create_project supports two kinds of templates:

• template="sdk" (default) — the SDK-style project generated by this package. It targets net472, has no VS-specific imports, and is the best choice for AI/CI builds.

• template="bare", "core", "disableable" — the official Visual Studio templates from denpadokei/UnityModdingTools.Templates.BeatSaber (branch denpadokei-dev). The template files are vendored into the wheel (MIT; see src/bsmt_mcp/template_data/official/SOURCE.json), expanded without Visual Studio, and post-processed for the project name, version, manifest and BeatSaberDir.

# official templates
bsmt templates list
bsmt create .\MyMod --template core --name "My Mod" --game "D:\...\Beat Saber"
bsmt create .\MyMod --template disableable --id MyMod --author me

# use a newer checkout of the template repository instead of the bundled copy
bsmt templates list --templates-dir C:\source\UnityModdingTools.Templates.BeatSaber
bsmt create .\MyMod --template bare --templates-dir C:\source\UnityModdingTools.Templates.BeatSaber

BSMT_TEMPLATES_DIR is also honored. The template engine supports $safeprojectname$, $projectname$, $rootnamespace$, $guid1$/$guid2$, $targetframeworkversion$, $registeredorganization$, $year$, simple $if$/$endif$ conditions, and ProjectItem target mappings.

Item templates

add_item_template adds the official item templates to an existing project:

bsmt item add .\MyMod --template harmony-patch --name MyPatch --directory Patches
bsmt item add .\MyMod --template bsml-viewcontroller --name SettingsView --directory UI
bsmt item add .\MyMod --template monobehaviour --name Runner --directory Behaviours

Required references are resolved from the project's BeatSaberDir (or --game) and added automatically; pass --no-references to skip that. For SDK-style projects the .cs files are included implicitly, while .bsml files are added as <EmbeddedResource> with <DependentUpon>. For legacy projects both <Compile> and <EmbeddedResource> items are added.

Requirements and setup

• Windows 10/11 for game detection and deployment.

• MSBuild from Visual Studio Build Tools/VS (legacy projects), or the .NET SDK (SDK-style projects). bsmt doctor reports what was found.

• For net472 projects, install the .NET Framework 4.7.2 targeting pack (included in the .NET desktop development workload).

• NuGet restore needs network access on the first build, unless the packages are already in the global NuGet cache.

No Visual Studio IDE is required. Build Tools are enough for legacy projects.

How the tricky parts are handled

BeatSaberDir and .csproj.user

MSBuild imports <project>.csproj.user through Microsoft.Common.props, so the extension's BeatSaberDir convention keeps working from the command line. set_game_directory updates any existing definition first (project, .csproj.user, nearest Directory.Build.props) and creates a .csproj.user only when nothing defines it.

Manifest embedding

BSIPA reads <AssemblyName>.manifest.json from the assembly's embedded resources. Projects using BeatSaberModdingTools.Tasks either embed the source manifest.json (RootNamespace must equal AssemblyName, the usual case) or let the package generate it. When the package is absent, generate_manifest(embed=true) adds:

<ItemGroup>
  <EmbeddedResource Include="manifest.json">
    <LogicalName>$(AssemblyName).manifest.json</LogicalName>
  </EmbeddedResource>
</ItemGroup>

It deliberately skips this when ImportBSMTTargets is enabled, avoiding duplicate resource names (CS1508).

Offline references

copy_game_references mirrors Beat Saber_Data/Managed, Libs, and Plugins into a local Refs folder (default: the parent of the project folder) and can point BeatSaberDir there. The usual $(BeatSaberDir)\Beat Saber_Data\Managed\Main.dll HintPaths then resolve without the game installed, which is useful for CI.

CLI reference

bsmt detect [--game PATH] [PATH ...]
bsmt doctor
bsmt inspect PROJECT [-c Debug]
bsmt refs list [PROJECT] [--game PATH] [--filter NAME] [--missing]
bsmt refs add PROJECT [--name DLL] [--preset core] [--game PATH] [--dry-run]
bsmt refs remove PROJECT --name DLL [--keep-non-game] [--dry-run]
bsmt refs copy PROJECT [--destination DIR] [--game PATH] [--no-set-dir]
bsmt setup PROJECT [--game PATH] [--target auto|user|project|props] [--reference-path]
bsmt manifest show PROJECT
bsmt manifest validate PROJECT
bsmt manifest generate PROJECT [--id ID] [--version 1.2.3] [--game-version 1.44.1] [--depends-on BSIPA=^4.3.0]
bsmt set-version PROJECT VERSION [--no-manifest] [--no-assembly] [--dry-run]
bsmt assembly PROJECT
bsmt compare MANIFEST_VERSION ASSEMBLY_VERSION
bsmt git PROJECT
bsmt build PROJECT [-c Release] [--package] [--deploy] [--property K=V]
bsmt package PROJECT [-c Release] [--extra SOURCE=DEST] [--include-manifest]
bsmt deploy PROJECT [-c Release] [--game PATH]
bsmt create PATH [--name NAME] [--id ID] [--author AUTHOR] [--template sdk|bare|core|disableable] [--templates-dir DIR]
bsmt templates list [--templates-dir DIR]
bsmt item add PROJECT --template harmony-patch|bsml-file|bsml-viewcontroller|monobehaviour --name NAME [--directory DIR] [--namespace NS] [--game DIR] [--no-references] [--no-project] [--force]
bsmt replace FILE PATTERN SUBSTITUTE [--regex]
bsmt github-output NAME VALUE [--path FILE]
bsmt mcp

All commands print JSON and exit non-zero when the operation reports ok: false.

Troubleshooting

uvx cannot acquire a lock / access denied (sandboxed environments). Set UV_CACHE_DIR to a writable directory:

$env:UV_CACHE_DIR = "$PWD\.uv-cache"
uvx --from git+https://github.com/denpadokei/BeatSaberModdingToolsMCP bsmt doctor

MSBuild.exe not found. Install Visual Studio Build Tools with the .NET desktop development workload, or use an SDK-style project and the .NET SDK (--prefer dotnet).

Game not detected. Pass --game "D:\...\Beat Saber" or set BEATSABER_DIR. BS Manager installs are auto-detected from %APPDATA%\bs-manager\config.json.

CS0006 / missing $(BeatSaberDir) DLLs. Run bsmt setup . --target user, then bsmt refs add . --preset core --preset bsipa.

Manifest version mismatch on Release. bsmt compare <manifest version> <assembly version> shows the BSMT rules (prerelease labels are ignored; 1.2.3 matches 1.2.3.0).

NU1301 / NuGet TLS errors. Restore needs access to nuget.org (or a local cache/mirror). The build itself works offline once the packages are cached.

日本語

Beat Saber の PC Mod（BSIPA）を Visual Studio を使わずに AI エージェントでビルドするための MCP サーバー兼 CLI です。BeatSaberModdingTools 拡張機能と BeatSaberModdingTools.Tasks の 主要機能を Python で再実装しています。

• ゲームの検出（Steam / Oculus / BS Manager）、BeatSaberDir の自動設定

• 参照 DLL の追加・削除、ローカル Refs へのコピー（オフラインビルド用）

• manifest.json の生成・検証・アセンブリへの埋め込み

• MSBuild / dotnet でのビルド、BeatMods 形式 zip の作成、Plugins / IPA/Pending への配置

• AssemblyInfo のバージョン比較、git 情報、ReplaceInFile 相当

• 公式プロジェクトテンプレート（bare / core / disableable）と アイテムテンプレート（Harmony / BSML / BSML ViewController / MonoBehaviour）

• 24 個の MCP ツールと bsmt CLI

{
  "mcpServers": {
    "beatSaberModdingTools": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/denpadokei/BeatSaberModdingToolsMCP", "bsmt-mcp"]
    }
  }
}

GitHub Copilot（VS Code / Copilot CLI）の設定は GitHub Copilot での使い方 に記載しています。

uvx はパッケージ指定に --from が必要なので、run エイリアスも同梱しています。

uvx --from git+https://github.com/denpadokei/BeatSaberModdingToolsMCP run

最初に detect_game → inspect_project → set_game_directory → add_game_references → generate_manifest → build_mod(package=true, deploy=true) の順に呼ぶのがおすすめです。 build_mod は失敗時も ok=false とコンパイラ診断を返します。

Visual Studio 本体は不要ですが、レガシー csproj のビルドには Build Tools の MSBuild、 SDK スタイルなら .NET SDK が必要です。bsmt doctor で検出状況を確認できます。

Development

git clone https://github.com/denpadokei/BeatSaberModdingToolsMCP
cd BeatSaberModdingToolsMCP
uv venv
# Non-editable install: editable .pth files break on Windows paths containing
# non-ASCII characters (Python reads .pth with the ANSI code page).
uv pip install --group dev .
uv run pytest
uv run ruff check

Layout:

src/bsmt_mcp/
  beatsaber.py    game detection, version parsing, reference inventory
  project.py      csproj inspection/editing, BeatSaberDir, reference copies
  manifest.py     manifest merge and schema validation
  assembly.py     AssemblyInfo/version comparison
  buildtools.py   MSBuild/dotnet, artifact, zip, deploy
  gitinfo.py      GetCommitInfo equivalent
  templates.py    project/item scaffolding
  vstemplate.py   Visual Studio .vstemplate expansion
  template_data/  vendored UnityModdingTools.Templates.BeatSaber (projects + items)
  ops.py          shared operations for MCP + CLI
  server.py       MCP tool definitions
  cli.py          bsmt CLI

License

MIT. See LICENSE. BeatSaberModdingTools and BeatSaberModdingTools.Tasks are MIT/ Unlicense projects by Zingabopp; this is an independent reimplementation and is not affiliated with Beat Games, BSMG, or the original authors.