Claude Code Windows Serena完全ガイド - Windows環境でセマンティックコード分析を実現

はじめに

Serena MCPは、Claude Codeに高度なコード分析機能を追加する強力なツールです。しかし、Windows環境では特有の設定上の課題があります。本記事では、Windows環境でSerena MCPを正しくセットアップし、効果的に活用する方法を詳しく解説します。

Serena MCPとは

概要

Serena MCPは、Oraios AIが開発した無料のオープンソースツールキットで、LLM（大規模言語モデル）を本格的なコーディングエージェントに変身させます。

主な特徴:

• セマンティック解析: コードの意味を理解した分析
• シンボルレベルの操作: 関数、クラス、変数を個別に認識
• 30以上の言語サポート: Python, TypeScript, Java, Go, Rustなど
• 無料でオープンソース: 誰でも利用可能

Serenaの機能

コード検索:

• セマンティック検索によるコード発見
• シンボル（関数、クラス、変数）の検索
• 依存関係の追跡

コード編集:

• シンボル単位での編集
• リファクタリング支援
• コード構造の理解

IDE機能の再現:

• 定義へのジャンプ
• 参照の検索
• コード補完支援

Windows環境での課題

PowerShell特有の問題

Windows環境でSerenaをインストールする際、以下の問題が発生することがあります：

問題1: 引数の解釈エラー

# このコマンドはWindows PowerShellでエラーになる
claude mcp add serena --from oraios/serena

エラーメッセージ:

error: unknown option '--from'

原因:

• PowerShellでの引数の解釈方法の違い
• --fromオプションが正しく認識されない

問題2: VS Codeターミナルでの動作不良

VS Code内蔵のターミナルでは、claude mcp addコマンドやuvxコマンドの引数が正しく渡らないことがあります。

Windows環境でのインストール手順

前提条件

必要なソフトウェア

1. Python（v3.10以降）
   1. Python公式サイトからインストール
   2. インストール時に「Add Python to PATH」を選択
2. uv（Python パッケージマネージャー）
   1. 高速なPythonパッケージマネージャー
   2. Serenaの実行に必要
3. Claude Code
   1. 最新版を推奨

Pythonのバージョン確認

python --version

期待される出力:

Python 3.10.x または 3.11.x, 3.12.x

方法1: 手動設定（推奨）

Windows環境では、設定ファイルを直接編集する方法が最も確実です。

1. uvのインストール

PowerShellまたはWindows Terminalで：

# uvをインストール
pip install uv

# またはpipxを使用（推奨）
pip install pipx
pipx install uv

2. uvの確認

uv --version

3. 設定ファイルの編集

プロジェクトの.claudeディレクトリにあるmcp.jsonを編集します。

ファイルパス:

C:\Users\<ユーザー名>\Projects\your-project\.claude\mcp.json

設定内容:

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/oraios/serena.git",
        "serena",
        "--directory",
        "."
      ],
      "transportType": "stdio"
    }
  }
}

重要なポイント:

• argsは配列として各引数を分割
• --fromとgit+https://...を別々の要素として指定
• --directoryと.も別々の要素として指定

4. グローバル設定（全プロジェクト共通）

全プロジェクトでSerenaを使用する場合は、ユーザー設定ファイルを編集します。

ファイルパス:

C:\Users\<ユーザー名>\.config\claude-code\mcp.json

または：

%APPDATA%\claude-code\mcp.json

設定内容は同様です。

5. Claude Codeの再起動

設定変更後、Claude Codeを再起動します。

# Claude Codeを終了（Ctrl+C）
# 再起動
claude

方法2: PowerShell 7での直接インストール

PowerShell 7を使用している場合は、コマンドラインからの追加も可能です。

PowerShell 7のインストール

winget install --id Microsoft.Powershell --source winget

Serena MCPの追加

PowerShell 7で：

claude mcp add serena `
  --command uvx `
  --arg "--from" `
  --arg "git+https://github.com/oraios/serena.git" `
  --arg "serena" `
  --arg "--directory" `
  --arg "."

注意:

• バッククォート（`）を使用して行を継続
• 各引数を--argで個別に指定

方法3: Git Bashでの設定

Git Bashを使用している場合：

# .claude/mcp.json を直接編集
cd /c/Users/<ユーザー名>/Projects/your-project/.claude
nano mcp.json

設定内容は方法1と同じです。

インストールの確認

MCPサーバーの確認

claude mcp list

期待される出力:

✓ serena (project) - Connected

Serenaの動作テスト

Claude Codeを起動して、以下のようにテストします：

claude

# プロンプト内で
「このプロジェクトのコード構造を分析して」

Serenaが正常に動作していれば、詳細なコード分析結果が返されます。

Windows環境での最適化

環境変数の設定

Serenaのパフォーマンスを向上させるための環境変数：

PowerShellプロファイルに追加:

# プロファイルを編集
notepad $PROFILE

# 以下を追加
$env:SERENA_CACHE_DIR = "$env:LOCALAPPDATA\serena\cache"
$env:SERENA_MAX_WORKERS = "4"

設定項目:

• SERENA_CACHE_DIR: キャッシュの保存場所
• SERENA_MAX_WORKERS: 並列処理数（CPUコア数に応じて調整）

パフォーマンスの最適化

Windows Defenderの除外設定

開発フォルダをWindows Defenderから除外：

1. Windowsセキュリティを開く
2. 「ウイルスと脅威の保護」→「設定の管理」
3. 「除外」→「除外の追加または削除」
4. プロジェクトフォルダを追加

推奨除外パス:

• C:\Users\<ユーザー名>\Projects\
• %LOCALAPPDATA%\serena\

uvキャッシュの場所

uvのキャッシュは以下に保存されます：

%LOCALAPPDATA%\uv\cache\

実践的な使用例

ユースケース1: コードベースの理解

質問:

「認証ロジックがどこに実装されているか教えて」

Serenaの動作:

1. コードベース全体をスキャン
2. 認証関連のシンボルを検索
3. 関連ファイルと依存関係を特定
4. 構造化された結果を提示

ユースケース2: リファクタリング

質問:

「UserServiceクラスをリファクタリングして、責任を分離したい」

Serenaの動作:

1. UserServiceクラスの構造を分析
2. メソッドの依存関係を特定
3. 分割可能な箇所を提案
4. 影響範囲を評価

ユースケース3: バグの特定

質問:

「このエラーログに関連するコードを探して」

Serenaの動作:

1. エラーメッセージから関連コードを検索
2. スタックトレースを分析
3. 該当する関数やクラスを特定
4. 修正候補を提案

ユースケース4: 依存関係の追跡

質問:

「このAPIエンドポイントを使っている箇所をすべて見つけて」

Serenaの動作:

1. APIエンドポイントの定義を検索
2. 呼び出し箇所をすべて特定
3. 依存関係グラフを作成
4. 影響範囲を可視化

トラブルシューティング

問題1: Serenaが起動しない

エラーメッセージ

Failed to connect to MCP server 'serena'

対処法

1. uvのインストールを確認:

uv --version

2. Pythonのバージョンを確認:

python --version

Python 3.10以降が必要です。

3. 設定ファイルを再確認:

# mcp.jsonの内容を確認
Get-Content .claude\mcp.json

4. Claude Codeを再起動:

# 完全に終了してから再起動
claude

問題2: PowerShellでの引数エラー

エラーメッセージ

error: unknown option '--from'

対処法

方法1: 手動設定を使用

claude mcp addコマンドではなく、.claude/mcp.jsonを直接編集してください。

方法2: PowerShell 7を使用

Windows PowerShell（5.1）ではなく、PowerShell 7を使用：

# PowerShell 7で実行
pwsh
claude mcp add serena ...

問題3: パスの問題

エラーメッセージ

Directory not found: .

対処法

相対パスではなく絶対パスを指定:

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/oraios/serena.git",
        "serena",
        "--directory",
        "C:\\Users\\<ユーザー名>\\Projects\\your-project"
      ],
      "transportType": "stdio"
    }
  }
}

注意: Windowsのパスは\\でエスケープが必要です。

問題4: パフォーマンスが遅い

対処法

1. キャッシュの場所を確認:

# キャッシュディレクトリを確認
dir $env:LOCALAPPDATA\uv\cache

2. キャッシュをクリア:

# uvキャッシュをクリア
uv cache clean

3. ワーカー数を調整:

mcp.jsonに環境変数を追加：

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [...],
      "env": {
        "SERENA_MAX_WORKERS": "2"
      },
      "transportType": "stdio"
    }
  }
}

問題5: Gitからのクローンに失敗

エラーメッセージ

Failed to clone repository

対処法

1. Gitがインストールされているか確認:

git --version

2. ネットワーク接続を確認

3. HTTPSプロキシの設定（必要な場合）:

# Gitのプロキシ設定
git config --global http.proxy http://proxy.example.com:8080

他のMCPとの組み合わせ

Serenaは他のMCPサーバーと組み合わせることで、さらに強力になります。

Serena + Context7

組み合わせの効果:

• Serena: セマンティック解析
• Context7: 高度な検索

設定例:

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/oraios/serena.git",
        "serena",
        "--directory",
        "."
      ],
      "transportType": "stdio"
    },
    "context7": {
      "command": "npx",
      "args": [
        "@context7/mcp-server"
      ],
      "transportType": "stdio"
    }
  }
}

活用シーン:

• Serenaでコード構造を理解
• Context7でプロジェクト全体を検索

Serena + GitHub MCP

組み合わせの効果:

• Serena: コード分析
• GitHub: リポジトリ情報

活用シーン:

• Issueに関連するコードをSerenaで分析
• PRの影響範囲をSerenaで評価

Serena + Gemini検索

組み合わせの効果:

• Serena: ローカルコード分析
• Gemini: Web上の最新情報

活用シーン:

• ライブラリの使用例をGeminiで検索
• プロジェクト内の実装をSerenaで確認

ベストプラクティス

効果的な質問の仕方

良い質問:

• 「認証ロジックの実装場所を教えて」
• 「データベース接続の処理を見せて」
• 「このAPIの呼び出し箇所をすべて教えて」

避けるべき質問:

• 「コードを見せて」（曖昧すぎる）
• 「全部教えて」（範囲が広すぎる）

プロジェクト構造の最適化

推奨事項:

• 適切なディレクトリ構造
• 明確な命名規則
• コメントとドキュメントの充実

定期的なメンテナンス

実施項目:

# 週次
uv cache clean

# 月次
# Serenaの更新確認（GitHubリリースページ）
# Claude Codeの更新
npm update -g claude-code

まとめ

Windows環境でSerena MCPを活用することで、Claude Codeのコード分析能力を大幅に向上させることができます。

重要なポイント:

• Windows環境では手動設定（mcp.json編集）が最も確実
• PowerShellでの引数の扱いに注意
• uvのインストールが必須
• Python 3.10以降が必要
• 他のMCPと組み合わせることでさらに強力に
• 定期的なメンテナンスでパフォーマンスを維持

次のステップ:

• 他のMCPサーバーとの組み合わせを試す
• カスタムスラッシュコマンドの作成
• プロジェクトテンプレートの整備

詳細な情報はSerena公式GitHubおよびClaude Code公式ドキュメントをご確認ください。

参考リンク:

• Serena公式GitHub
• Claude Code MCP公式ドキュメント
• uv公式サイト
• Model Context Protocol仕様