🧰
Serena MCP Server 導入ガイド（Windows ARM64／Claude Code & GitHub Copilot対応）
Serena MCP Server 導入ガイド（Windows ARM64／Claude Code & GitHub Copilot対応）
TL;DR
- まず uv / uvx を入れる
- Windows ARM64 でビルドが落ちたら、x64 の Python 3.12 を入れて
UV_PYTHONで指定- Claude Code と GitHub Copilot（MCP） の設定例を本文に記載
spawn uvx ENOENTは PATH か絶対パス、win_arm64ビルド失敗は x64 3.12 で回避
0. Serena とは？
Serena は MCP（Model Context Protocol）サーバ。LSP を使ってコードベースを理解し、LLM（例：Claude）にシンボル単位の検索・編集を提供します。
- 「行番号ベースの置換」ではなく、構造（シンボル）に基づく安全な編集が可能
- Claude Code / Claude Desktop / GitHub Copilot（MCP対応） などから利用できます
1. 前提ツールのインストール
1-1. uv / uvx を入れる（PowerShell）
powershell -ExecutionPolicy Bypass -c "irm https://astral.sh/uv/install.ps1 | iex"
# 代替: winget install --id=astral-sh.uv -e
uv --version
uvx --help
1-2. （重要）x64 の Python 3.12 を用意
Windows ARM64 + 一部のネイティブ拡張は ARM64/3.13 だと wheel がなくビルド落ちしがち。
x64（win_amd64）の Python 3.12 を追加インストールして使わせるのが安定です。
- [python.org → Windows] から “Windows installer (64-bit)”（= x86-64）を選択
- 例：
C:\Users\<YOU>\AppData\Local\Programs\Python\Python312\python.exe - “Add python.exe to PATH” をON、Microsoft Store のアプリ実行エイリアス（Python/Python3）をOFFにすると衝突しづらい
どこに入ったか確認
py -0p
py -3.12 -c "import sys,platform; print(sys.executable); print(platform.machine())"
2. まずはコマンドラインで起動（お試し）
2-1. そのシェルだけ x64 3.12 を使わせる
$env:UV_PYTHON = "C:\Users\<YOU>\AppData\Local\Programs\Python\Python312\python.exe"
uv cache clean
2-2. Serena をワンライナー起動
uvx --from git+https://github.com/oraios/serena `
serena start-mcp-server --context ide-assistant --project "$PWD"
ログに
cp312-win_amd64が見えれば OK。
cp313-win_arm64が出るならUV_PYTHONが効いていない可能性あり（パス再確認）。
3. GitHub Copilot（MCP）設定（VS Code）
settings.json（ユーザー or ワークスペース）に mcpServers を追加します。
PATH問題を避けるため、uvx ではなく uv tool run + --python 明示が安定です。
{
"mcpServers": {
"serena": {
"command": "uv",
"args": [
"tool", "run",
// ★ Windows ARM64：x64 Python 3.12 を明示
"--python", "C:\\\\Users\\\\<YOU>\\\\AppData\\\\Local\\\\Programs\\\\Python\\\\Python312\\\\python.exe",
"--from", "git+https://github.com/oraios/serena",
"serena", "start-mcp-server",
"--context", "ide-assistant",
"--project", "${workspaceFolder}"
]
}
}
}
-
\\は JSON 上で 二重 にする -
spawn uvx ENOENTが出ていた場合でも、上記のuv tool run直叩きで回避しやすい - 依存が壊れたら VS Code 再起動前に
uv cache cleanでリトライ
4. Claude Code（CLI）設定
4-1. MCP サーバの登録（PowerShell）
# uvx が使える場合（お試し）
claude mcp add serena -- `
uvx --from git+https://github.com/oraios/serena `
serena start-mcp-server --context ide-assistant --project "$PWD"
uvx が見つからない／PATHが通らない場合は uv tool run に変更：
claude mcp add serena -- `
uv tool run --python "C:\Users\<YOU>\AppData\Local\Programs\Python\Python312\python.exe" `
--from git+https://github.com/oraios/serena `
serena start-mcp-server --context ide-assistant --project "$PWD"
4-2. 起動・確認
claude mcp list
claude mcp start serena
以後、Claude Code から Serena のツール（シンボル検索・安全編集など）が利用可能になります。
5. 速度最適化（大規模リポ向け）
初回の理解を速くしたい場合は 事前インデックスが有効です。
uvx --from git+https://github.com/oraios/serena `
serena project index --project "$PWD"
6. よくあるエラーと対処（Windows ARM64 編）
| 症状 | 主原因 | 解決策 |
|---|---|---|
spawn uvx ENOENT |
拡張ホストから uvx が見えない |
command を uv にして tool run 直叩き／uvx の絶対パス指定 |
Unsupported platform: win_arm64 / maturin 失敗 |
ARM64/3.13 で wheel が無くソースビルド落ち |
x64 Python 3.12 を入れて UV_PYTHON or --python 指定／uv cache clean 後に再試行 |
| 依存は落ちないが遅い | 初回インデックス未実施 |
serena project index を先に実行 |
| Filesystem MCP と競合 | Serena側のFS操作と重複 | MCPクライアント設定でどちらか片方を無効化 |
7. 永続化と運用のコツ
-
UV_PYTHONをユーザー環境変数に保存（毎回指定が不要に）[Environment]::SetEnvironmentVariable( "UV_PYTHON", "C:\\Users\\<YOU>\\AppData\\Local\\Programs\\Python\\Python312\\python.exe", "User" ) -
バージョン固定：運用が安定したら Serena/依存のバージョンを控えておく（更新が活発なため）
-
安全運用：危険なシェル実行は MCP クライアント側の許可設定（permissions）でブロック
-
WSL という保険：どうしても Windows ARM64 直で辛い場合、WSL2（Ubuntu ARM64）上の uv/uvx で Serena を起動すると安定
8. 片付け
uv cache clean # uv のキャッシュ掃除
# VS Code: settings.json の mcpServers から serena を削除
# Claude Code: claude mcp remove serena
まとめ
- Windows ARM64 でも、x64 Python 3.12 を使わせるだけで Serena の導入はぐっと安定
-
GitHub Copilot（MCP） は
uv tool run+--python明示、Claude Code はclaude mcp addで登録 -
spawn uvx ENOENTとwin_arm64系エラーを潰せば、シンボル単位の安全な編集が快適に使える
Discussion