【備忘録】Serenaセットアップ：Windows でよくあるエラーと対処法

この備忘録について

Serenaの導入方法としてよく紹介されているコマンドを Windows で実行すると、様々なエラーが発生します。

よく見かける推奨コマンド：

claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena-mcp-server --context ide-assistant --project $(pwd)

この備忘録では、このコマンドを Windows で実行した際に発生する実際のエラーとその解決方法を段階的に記録しています。同じ問題で困った際の参考用です。

前提条件

• Windows 10/11環境
• Claude Code がインストールされている
• Python がインストールされている（pip コマンドが使える）
• 基本的なコマンドライン操作ができる

実際に発生するエラーと対処の流れ

【エラー1】よく紹介されているコマンドを実行すると...

Windows PowerShell で推奨コマンドをそのまま実行：

claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena-mcp-server --context ide-assistant --project $(pwd)

エラー結果：

error: unknown option '--from'

原因： Windows版のClaude CLIは、よく紹介されている構文とは異なります。

---

【対処法1】まずは環境を整える

1-1. uvツールをインストール

このエラーの前に、まず必要なツールをインストールします：

pip install uv

成功例：

Successfully installed uv-0.8.4

1-2. uvが正しく動作するか確認

uv --version

エラーが出る場合：

uv : 用語 'uv' は、コマンドレット、関数、スクリプト ファイル、または操作可能なプログラムの名前として認識されません

対処法： python -m を付けて実行：

python -m uv --version

成功例：

uv 0.8.4 (e176e1714 2025-07-30)

1-3. Serenaが動作するかテスト

python -m uv tool run --from git+https://github.com/oraios/serena serena-mcp-server --help

初回実行時の成功例：

Updated https://github.com/oraios/serena (9af709eb7b8d7221c3dfd782593fb609dec55202)
Built serena-agent @ git+https://github.com/oraios/serena@9af709eb7b8d7221c3dfd782593fb609dec55202
Installed 57 packages in 8.32s

このメッセージが出れば、Serenaのダウンロードとビルドが成功です！

---

【対処法2】正しい構文でClaude MCPに追加

元のコマンドの構文は Windows の Claude CLI では動作しません。以下の正しい構文を使用します：

試行1（失敗例）：

claude mcp add serena "python -m uv tool run --from git+https://github.com/oraios/serena serena-mcp-server" --context ide-assistant --project C:\Users\ユーザー名

エラー結果：

error: unknown option '--context'

試行2（成功例）：

--context と --project オプションもSerenaのオプションなので、全て引用符内に入れます：

claude mcp add serena "python -m uv tool run --from git+https://github.com/oraios/serena serena-mcp-server --context ide-assistant --project C:\Users\ユーザー名"

成功結果：

Added stdio MCP server serena with command: python -m uv tool run --from git+https://github.com/oraios/serena serena-mcp-server --context ide-assistant --project C:\Users\ユーザー名 to local config
File modified: C:\Users\ユーザー名\.claude.json [project: C:\WINDOWS\system32]

---

【対処法3】Claude Code での初期化

Claude Code に戻り、よく紹介されている初期化コマンドを実行：

試行1（失敗例）：

/mcp__serena__initial_instructions

エラー結果：

Error: Unknown command: /mcp__serena__initial_instructions. Available commands: /init, /pr-comments, /review

試行2（成功例）：

利用可能なコマンドが表示されるので、正しいコマンドを使用：

/init

成功結果：

/init is analyzing your codebase…
Listed 917 paths (ctrl+r to expand)
Search(pattern: "**/*.md")
Search(pattern: "**/*.json")  
Search(pattern: "**/*.py")
Philosophising… (22s)

完了時のメッセージ例：

Perfect! I've successfully updated your CLAUDE.md file with significant improvements that better serve the Serena MCP initialization and your development workflow. Here are the key enhancements I've made:

🏗️ Major Improvements Added
1. Development Environment & Architecture Section
2. Common Development Commands  
3. Technology Stack & Dependencies
4. Competition-Specific Patterns
5. MCP Integration & Serena Configuration

🎯 Key Benefits
1. Better Architecture Understanding
2. Comprehensive Command Reference
3. Integrated Workflows
4. MCP-Ready
5. Maintains Your Existing Structure

The file now serves as both a comprehensive development guide and maintains all your competitive data science configurations.

この表示が出れば、Serenaがプロジェクトを完全に分析し、CLAUDE.mdファイルが大幅に強化された証拠です。

※ここは違う気がするので調査

完了時のメッセージ例：

Perfect! I've successfully updated your CLAUDE.md file with significant improvements that better serve the Serena MCP initialization and your development workflow. Here are the key enhancements I've made:

🏗️ Major Improvements Added
1. Development Environment & Architecture Section
2. Common Development Commands  
3. Technology Stack & Dependencies
4. Competition-Specific Patterns
5. MCP Integration & Serena Configuration

🎯 Key Benefits
1. Better Architecture Understanding
2. Comprehensive Command Reference
3. Integrated Workflows
4. MCP-Ready
5. Maintains Your Existing Structure

The file now serves as both a comprehensive development guide and maintains all your competitive data science configurations.

この表示が出れば、Serenaがプロジェクトを完全に分析し、CLAUDE.mdファイルが大幅に強化された証拠です。

Windows環境での最終的な正解コマンド

よく紹介されているコマンドがエラーになった場合、以下の手順が Windows での正解です：

1. 前準備

pip install uv

2. Serenaの追加

claude mcp add serena "python -m uv tool run --from git+https://github.com/oraios/serena serena-mcp-server --context ide-assistant --project C:\Users\あなたのユーザー名"

3. 初期化

Claude Code で：

/init

なぜよく紹介されているコマンドが Windows で動かないのか？

よく見かける推奨コマンド：

claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena-mcp-server --context ide-assistant --project $(pwd)

Windows で問題となる点：

1. uvx コマンドが存在しない → python -m uv tool run を使用
2. --from がClaude CLIのオプションとして認識される → 全体を引用符で囲む必要
3. $(pwd) はLinux/Mac の記法 → Windows では具体的なパスを指定
4. 初期化コマンドが異なる → /mcp__serena__initial_instructions ではなく /init ※ここは違う気がするので調査

備忘録まとめ

よく紹介されている手順通りにやったのにエラーが出る！ という Windows ユーザーは、上記の手順で解決できる可能性があります。

Linux/Mac 向けの手順をそのまま Windows で実行すると、コマンドの構文や利用可能なツールが異なるため、エラーが発生することがあります。この備忘録の手順を参考にすれば、Windows 環境でも Serena をセットアップできるはずです。