Zenn
🔗

WSL + Claude Code + MCP環境構築ガイド＋α【2025年6月版】

に公開
1件
開発環境
Windows
WSL
Model Context Protocol
Claude
tech

WSL + Claude Code + MCP環境構築ガイド＋α

WSLでClaude Codeを使いながら、Windows側のClaude DesktopからMCP経由で統合制御し、効率的なAI支援でのWindowsアプリ開発を行う環境の構築手順をまとめました。

これまで「WSLかWindowsか」で悩んでいた方に、Claude Codeを中心とした両環境の利点を活用できる実用的な環境をご紹介します。

🎯 この環境でできること

主な機能とメリット

  1. WSLでClaude Code開発

    • Claude CodeのAI支援機能をフル活用
    • WSL環境でのシームレスなファイル操作
    • 豊富なLinux開発ツールとの連携

  2. Windowsファイルへのシームレスアクセス

    • WSLから/mnt/c/でWindows側ファイルにアクセス
    • ファイル同期の手間が不要
    • エディタやIDEとの連携

  3. Claude Desktop統合

    • Windows側Claude DesktopでWSL側Claude Codeを制御
    • MCP経由での統合管理
    • GUIの使いやすさとCLIの強力さを両立

  4. 効率的な開発フロー

    • WSL側で開発、Windows側で動作確認
    • 用途に応じた環境の使い分け
    • クロスプラットフォーム開発対応

  5. Windows側UI確認の効率化（＋α）

    • App Vision MCP(独自開発)でWindows画面をキャプチャおよびAI分析
    • WSL開発中でもWindows側のUI/UX改善提案を取得
    • 画面キャプチャ → AI解析 → 改善提案の自動化ワークフロー

📋 システム構成について

この環境では、Windows環境とWSL環境が密接に連携し、ファイル共有とMCP統合により効率的な開発フローを実現します。Claude DesktopからWSL環境のClaude CodeをMCP経由で制御することで、GUIとCLIの利点を併用できる統合開発環境を構築します。

⚙️ システム環境の構築

重要: 以下のStep 1-3で基本システム環境を構築します。Claude Codeインストール完了後、実際の開発は作業フォルダ（/mnt/c/YourProject）で行います。

Step 1: WSL環境のセットアップ

目的: Windows上にLinux開発環境を構築し、Claude Code実行基盤を準備します。

1-A: WSLインストール（Windows側作業）

# PowerShellを管理者権限で起動して実行
wsl --install

実行のポイント:

  • 管理者権限必須: PowerShellを「管理者として実行」で起動してください
  • 自動選択: 最新のUbuntu LTS版（通常はUbuntu 22.04）が自動選択されます
  • 自動機能有効化: WSL機能、仮想マシンプラットフォーム、Linuxカーネルが自動で有効化されます
  • システム再起動: インストール完了後、必ずシステムを再起動してください

1-B: 初回セットアップ（WSL側作業）

システム再起動後、Ubuntuターミナルが自動起動します。以下を完了してください：

# ユーザー名とパスワードを設定
Username: [任意のユーザー名を入力]
Password: [任意のパスワードを入力]

# システム更新（推奨）
sudo apt update && sudo apt upgrade -y

セットアップ完了の確認:

# WSL環境の確認
whoami          # 設定したユーザー名が表示される
pwd             # /home/username が表示される
lsb_release -a  # Ubuntu のバージョン情報が表示される

Step 2: Node.js環境構築（WSL側作業）

目的: Claude Codeの動作に最適化されたNode.js環境をWSLシステム内にセットアップします。

シンプルなセットアップ手順:

# 1. NVM (Node Version Manager) をインストール
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc

# 2. 最新LTS版Node.jsをインストール
nvm install --lts
nvm use --lts

# 3. インストール確認
node --version  # LTSバージョンが表示される
npm --version   # npmバージョンが表示される

ステップ別詳細説明:

ステップ1: NVMインストール

  • バージョン管理機能: 複数のNode.jsバージョンを簡単に切り替え可能
  • クリーンなインストール: システムレベルの競合を回避
  • 自動PATH設定: .bashrcに自動でPATH設定が追加される

ステップ2: LTS版Node.js選択

  • 自動LTS選択: --ltsフラグで最新の長期サポート版を自動選択
  • Claude Code対応: LTS版でClaude Code機能をフルサポート
  • 将来性: 新しいLTS版がリリースされても自動対応

ステップ3: 環境確認

  • Node.js確認: LTS版が適切にインストールされたことを確認
  • npm確認: Node.jsと一緒にnpmも正常にインストールされていることを確認
  • 次段階準備: Claude Codeインストールの準備完了

Step 3: Claude Codeインストール（WSL側作業）

目的: WSLシステム環境にClaude Codeをインストールし、グローバルコマンドとして使用可能にします。

# Claude Code をグローバルインストール
npm install -g @anthropic-ai/claude-code

# インストール確認
claude --version  # Claude Codeバージョンが表示される
which claude      # Claude Codeのインストールパスが表示される

グローバルインストールの利点:

  • システム全体で利用可能: どのディレクトリからでもclaudeコマンドが実行可能
  • NVM環境統合: NVM管理下で適切にパス設定される
  • 複数プロジェクト対応: 異なる作業フォルダで同一のClaude Codeを共用

システム環境構築完了の確認:

# 全体動作確認
node --version    # LTSバージョンが表示される
npm --version     # npmバージョンが表示される
claude --version  # Claude Codeバージョンが表示される
which claude      # 実際のインストールパスが表示される

重要な確認ポイント:

  • Node.js: LTS版が適切に動作している
  • npm: パッケージマネージャーが正常に動作している
  • Claude Code: 正常にインストールされパスが通っている
  • コマンド実行: エラーなく各コマンドが応答する

システム環境構築完了: この時点でWSLシステム環境の構築は完了です。次からは実際の開発作業を行うため、作業フォルダに移動します。

📁 作業フォルダでの開発開始

目的: システム環境構築完了後、実際の開発作業を開始します。

# Windows側プロジェクトフォルダに移動
cd /mnt/c/YourProject  # あなたの開発ディレクトリ

# 作業フォルダで初回認証・設定
claude

作業フォルダ使用の利点:

  • Windows連携: エディタやIDEでのファイル編集が容易
  • ファイル共有: WindowsとWSL間でリアルタイム同期
  • ブラウザ確認: Windows側でのWebアプリ動作確認が便利
  • バックアップ: Windows標準のバックアップ機能を活用可能

⚠️ ファイル配置に関する重要な検討事項

Windows側とWSL側の性能差について:

WSL環境から /mnt/c/ でWindows側ファイルにアクセスする場合と、WSL側（/home/ 等）でファイルを管理する場合では、パフォーマンスに明確な差があります。

パフォーマンス比較結果:

  • 軽微な操作（ファイル読み取り・ディレクトリ一覧）: 数ms程度の差で実用上問題なし
  • 大量操作（Grep検索・ファイル作成・書き込み）: 20倍〜75倍の速度差が発生

WSL側ファイル配置のメリット:

  • 高速な操作: ファイル操作全般が大幅に高速化
  • Linux環境統合: WSL環境での作業効率向上

WSL側ファイル配置のデメリット:

  • 🚨 バックアップ・リカバリの複雑化: WSLファイルシステムは仮想環境内に格納され、通常のWindowsバックアップソフトで認識困難
  • 🚨 WSL環境依存リスク: WSL更新時の互換性問題、Hyper-V無効化時のアクセス不可
  • 🚨 開発ツール互換性: Windows IDEからの直接アクセス困難、デバッガーやプロファイラーの制限
  • 🚨 データ可搬性の低下: 他PCへのコピーが複雑化（特殊なエクスポート手順が必要）
  • 🚨 ファイル共有の制約: ネットワーク共有でのアクセスが困難

本記事でのアプローチ:

本記事では Windows側ファイル配置（/mnt/c/）で環境構築 しています。選択理由：

  1. データ安全性の重視: 開発資産の保護とアクセシビリティを重視
  2. 実用上十分な性能: Claude Codeでの通常操作では性能差は軽微
  3. 運用の簡単さ: バックアップ・移行・共有が容易

パフォーマンス重視の場合の代替案:

  • ハイブリッドアプローチ: メインデータはWindows側、大量処理時のみWSL側で一時作業
  • 選択的高速化: 必要時にWSL側にコピー→処理→結果をWindows側に戻す

重要: ファイル配置は一度決めると変更が困難です。データの安全性、アクセシビリティ、バックアップ戦略を十分検討の上で決定してください。

初回認証の重要性:

  • プロジェクト固有設定: 作業ディレクトリでの設定を保存
  • セキュアな連携: Anthropic APIとの安全な認証を確立
  • ブラウザ認証: 初回起動時にWebブラウザで認証を完了

重要ポイント: この段階以降の作業は全て /mnt/c/YourProject フォルダ内で行います。Claude Codeのシステムインストールは完了しており、あとは実際の開発作業のみです。

🚀 ワンクリック起動バッチファイル

目的: Windows側からワンクリックでWSL環境のClaude Codeを起動できるようにします。

Claude Codeパスの確認

最重要: バッチファイルとMCP設定では、必ず実際の環境で確認したパスを使用してください。

# WSL環境で以下のコマンドを実行（最重要）
which claude  # Claude Codeの実際のパスを確認
whoami        # 実際のWSLユーザー名を確認

⚠️ 重要: 以下の設定例で使用する全てのパスとユーザー名は、上記コマンドで確認した実際の値に置き換えてください。

パス確認の例:

$ which claude
/home/username/.nvm/versions/node/v20.15.1/bin/claude
# または
/home/username/.nvm/versions/node/v22.11.0/bin/claude

NVM管理下のClaude Codeパス例:

  • NVMパス: /home/username/.nvm/versions/node/v[LTSバージョン]/bin/claude

重要な注意: 本記事ではNVMの--ltsフラグで最新LTS版をインストールしますが、実際のバージョン番号は環境により異なります（v20.x.x、v22.x.x等）。必ずwhich claudeコマンドで実際のパスを確認し、そのパスをバッチファイルとMCP設定で使用してください。usernameも実際のWSLユーザー名に置き換えてください。

バッチファイルの作成

シンプルで確実な起動スクリプト: 上で確認したパスを使用してバッチファイルを作成します。

C:\YourProject\Scripts\ClaudeCode.bat:

バッチファイル例:

@echo off
wsl -e bash -c "cd /mnt/c/YourProject && /home/username/.nvm/versions/node/v[実際のバージョン]/bin/claude --mcp-config /mnt/c/YourProject/mcp-config.json"
pause

バッチファイル作成の手順:

  1. パス確認: WSLで which claude を実行
  2. パスコピー: 表示されたパスをコピー
  3. バッチ作成: 上記テンプレートのパス部分を置き換え
  4. パス変更: /mnt/c/YourProject を実際のプロジェクトパスに変更
  5. MCP設定: mcp-config.json ファイルのパスを確認

バッチファイルの特徴:

  • NVMパス指定: NVM管理下のClaude Codeを直接起動
  • MCP設定連携: --mcp-config オプションで設定ファイルを指定
  • エラー確認: pause により、エラーメッセージを確認可能
  • プロジェクト固有: 特定のディレクトリとMCP設定に最適化

⚠️ 最重要: v[実際のバージョン]とusernameは、必ず上記のwhich claudeとwhoamiコマンドで確認した実際の値に置き換えてください。設定例をそのまま使用すると動作しません。

⚠️ バッチファイル起動時の注意点と代替手法

バッチファイル起動のリスク: 他の.batアプリケーションを開発中の場合、プロセス間の干渉により巻き添えで両方のアプリケーションが終了する可能性があります。その結果、Claude Codeでの貴重なコンテキスト（会話履歴）が失われてしまいます。

推奨される代替手法: 開発作業中は、Claude Codeではなく開発対象のアプリケーションをIDEで起動することをお勧めします。

使い分けの指針:

  • バッチファイル: 単発でのClaude Code使用時（学習・調査など）
  • IDE起動: 本格的な開発作業時（アプリ側をIDEで起動し、Claude Codeは必要時のみ利用）

📝 Claude Code側のMCP設定について

本記事の対象範囲: この記事では、基本的なWSL + Claude Code環境の構築に焦点を当てています。

Claude Code側のMCP設定ファイル: バッチファイルで指定している mcp-config.json の具体的な設定内容については、使用するMCPツールに応じて別記事で詳細に解説予定です。

対象となるMCPツール:

  • App Vision MCP（Windows画面解析）
  • その他の専用MCPサーバー
  • カスタムMCP設定

注意: App Vision MCPなどの高度なMCPツールを使用する場合は、Claude Code側にも専用の設定ファイルが必要になります。これらの設定方法については、各MCPツール専用の記事で詳しく説明いたします。

🔄 Claude Codeのアップデート

Claude Codeのアップデート確認: Claude Codeは右下にアップデート通知が表示されます。通知が出た際に以下のコマンドでアップデートしてください。

# WSL環境でClaude Codeを最新版にアップデート
npm update -g @anthropic-ai/claude-code

# バージョン確認
claude --version

実行のポイント:

  • Claude Code右下の通知でアップデートのタイミングを確認
  • 通知確認後、上記コマンドで簡単にアップデート可能

🔧 Claude Desktop MCP統合（オプション）

目的: Windows側のClaude DesktopからWSL環境のClaude Codeを統合利用できるようにします。

Claude Desktop設定ファイル

Windows側Claude Desktopとの統合: Claude DesktopからWSL環境のClaude Codeを呼び出せます。

%APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "claude_code": {
      "command": "wsl",
      "args": [
        "-e",
        "bash",
        "-l",
        "-c",
        "cd /mnt/c/YourProject && source ~/.nvm/nvm.sh && /home/username/.nvm/versions/node/v[実際のバージョン]/bin/claude mcp serve"
      ],
      "env": {}
    }
  }
}

設定の詳細説明

コマンド構成の解説:

  • -e: WSLで指定したコマンドを実行
  • bash -l: ログインシェルとして起動（環境変数を読み込み）
  • -c: 続くコマンド文字列を実行
  • claude mcp serve: Claude CodeをMCPサーバーモードで起動

パス確認方法:

# WSL環境で実際のパスを確認
which claude  # Claude Codeのパスを確認

カスタマイズのポイント:

  • /mnt/c/YourProject を実際のプロジェクトパスに変更
  • /home/username を実際のWSLユーザー名に変更
  • source ~/.nvm/nvm.sh によりNVM環境を読み込み
  • Node.jsバージョン（v[実際のバージョン]）は実際の環境に合わせて調整 - which claudeで確認した実際のパスを使用

注意: MCP設定でも、バッチファイルと同様に実際の環境で確認したパスとバージョン番号を使用してください。nvm install --ltsでインストールされる実際のLTSバージョンは時期により異なります（v20.x.x、v22.x.x等）。

MCP選択肢の比較

filesystem MCPサーバー vs Claude Code MCP:

公式filesystem MCPサーバーも利用可能ですが、本記事ではClaude Code MCPを推奨しています。

filesystem MCPの特徴:

  • Windows C:ドライブなどの記載がより素直
  • 純粋なファイル操作に特化

Claude Code MCPの利便性:

  • AI支援開発機能との統合
  • WSL環境でのコマンド実行
  • 開発ワークフロー全体をサポート

統合のメリット

  • デュアル環境: Claude Desktop（GUI）とClaude Code（CLI）の使い分け
  • 統一管理: 同一プロジェクトをどちらの環境からもアクセス可能
  • MCP経由: Claude DesktopからClaude Codeの全機能を利用可能

⚠️ Claude Desktop利用時の注意点

会話上限制限: Claude Desktopは1セッションあたりの会話上限が厳しく設定されています。そのため、継続的な開発作業では開発対象アプリをIDEで起動し、Claude Codeは必要時のみ利用することを推奨します。

推奨する使い分け:

  • Claude Desktop MCP: 短時間の調査・設定・簡単な修正
  • IDE + Claude Code: 本格的な開発（アプリ側をIDEで起動、Claude Codeは補助的に活用）

🎯 Claude Desktop + Claude Code MCP の実際の使い方

基本的な操作フロー

重要: Claude DesktopでMCP設定を完了していれば、Claude Codeを別途起動する必要はありません。Claude Desktopから直接Claude CodeのMCP機能を利用できます。

Claude Desktop でMCP機能を使用

  • Windows側のClaude Desktopで通常通り会話を行うだけで、自動的にWSL環境のファイル操作が可能
  • 特別なコマンドは不要で、直感的な操作で開発タスクを実行
  • 開発完了後はWindows側でブラウザ確認

使用感

Claude Desktopでの通常の会話を通じて、自然にWSL環境でのファイル操作や開発タスクが実行されます。特別なコマンドや複雑な操作は不要で、直感的な対話で開発を進めることができます。

🎨 Windows側アプリ画面の確認・分析

開発中のアプリケーションをWindows側で動作確認する際、画面の状態を分析・改善するためのツールとして、今回開発したApp Vision MCPを活用できます。

App Vision MCPの概要

Windows画面解析ツール - Windows Graphics Capture APIを活用して、開発中のアプリケーション画面をキャプチャ・AI分析し、UI/UX改善提案を生成するMCPツールです。

主な機能

  • 画面キャプチャ: 開発中のWebアプリ、デスクトップアプリの画面を高品質取得
  • AI分析: キャプチャした画面のUI要素、レイアウト、ユーザビリティを分析
  • 改善提案: 画面内容に基づく具体的な改善案の生成

開発ワークフローでの活用例

1. WSL環境でアプリ開発・実行
   ↓
2. Windows側ブラウザで動作確認
   ↓  
3. App Vision MCPで画面分析
   ↓
4. AI分析結果に基づく改善
   ↓
5. Claude Codeで即座に修正

App Vision MCP リポジトリ: https://github.com/git-ai-code/app-vision-mcp

これにより、WSL開発 + Windows画面分析の統合された開発体験が実現できます。

補足: App Vision MCPの詳細な設定方法（Claude Code側の mcp-config.json 設定を含む）については、App Vision MCP専用の記事で詳しく解説予定です。本記事では基本的なWSL + Claude Code環境構築に焦点を当てています。

📈 この環境のメリット

開発効率の向上

  • 環境構築の簡素化: WSL + Windowsの組み合わせでセットアップが容易
  • クロスプラットフォーム開発: 環境切り替えの手間を軽減
  • AI支援の活用: Claude Codeによる効率的な開発支援
  • リアルタイムフィードバック: Windows側での即座な動作確認

従来手法との比較

項目 従来のWSL 従来のWindows この環境
開発ツール Linux豊富 Windows限定 両方活用
ファイルアクセス 複雑 単純 統合
GUI統合 困難 簡単 両立
AI支援 限定的 限定的 フル活用
学習コスト 高 中 段階的

まとめ

この記事で紹介したWSL + Claude Code + MCPの環境は、開発効率の向上に役立つ実用的な構成です。

主な特徴：

  • Windows の使いやすさ
  • WSL の開発ツール
  • Claude Code のAI支援
  • MCP の統合機能

これらを組み合わせることで、より効率的な開発環境を構築できます。

特にバッチファイルによる簡単起動やMCP連携方法を具体的に示すことで、実用的なガイドとして活用いただけるはずです。

セットアップには時間がかかりますが、一度構築すれば長期的に開発効率の向上が期待できます。ぜひお試しください。

この記事が革新的な開発環境構築のお役に立てば幸いです。質問やフィードバックがあれば、ぜひコメント欄でお聞かせください！

Discussion

maitakemaitake

まさに悩んでいたことが記事化されていてエンジニア初学者にとって神です。ありがとうございます！