Serena MCP：詳細な使用ガイド（インストール、設定、実践）

Serena MCP は 強力なオープンソース AI コーディングエージェントツールキット であり、MCP サーバー として動作します。

これは Language Server Protocol (LSP) に基づく シンボルレベルの理解 を提供し、従来のテキスト検索ベース（例：RAG）の AI プログラミングツールが複雑なコードベースを扱う際の欠点を補います。

Serena MCP のユニークな点は、Claude Desktop アプリケーションを通じて無料で利用可能 であり、無料プランでも動作するため、API コストを回避できることです。

このチュートリアルでは、Serena MCP のインストール、設定、そして Claude Code Serena を含むさまざまなクライアントでの利用方法を詳しく解説します。

---

1. 環境準備とサーバー起動

Serena MCP は Python 環境に依存しており、uv ツールの使用が推奨されます。

1.1 前提条件：uv のインストール

Serena MCP のコマンドライン操作はすべて uv によって実行されるため、まずインストールしてください。

1.2 Serena MCP サーバーの起動

Serena MCP は MCP サーバー として起動する必要があります。通常、クライアント（例：Claude Desktop）はサブプロセスとしてこれを起動し、標準入出力（stdio）を通じて通信します。

uvx を使ったクイックスタート（推奨）

リポジトリをローカルにクローンせずに、uvx を使って最新の Serena MCP を直接実行できます：

uvx --from git+https://github.com/oraios/serena serena start-mcp-server

ローカルインストールと実行

1. リポジトリをクローン:

   git clone https://github.com/oraios/serena && cd serena

2. サーバーを起動:

   uv run serena start-mcp-server

3. インストールディレクトリ外から実行する場合はディレクトリを指定:

   uv run --directory /abs/path/to/serena serena start-mcp-server

Docker を利用（実験的）

Docker はローカルに言語サーバーをインストールせずに、より良い隔離環境と一貫性を提供します。プロジェクトディレクトリをコンテナにマウントしてください：

docker run --rm -i --network host -v /path/to/your/projects:/workspaces/projects ghcr.io/oraios/serena:latest serena start-mcp-server --transport stdio

ダッシュボードとログ

デフォルトで、Serena MCP は Web ダッシュボード（通常は http://localhost:24282/dashboard/index.html）を起動し、ログの表示や MCP サーバーの停止（クライアント終了後のゾンビプロセス防止）を可能にします。

---

2. クライアント設定（システム別統合）

Serena MCP は Model Context Protocol (MCP) をサポートするすべてのクライアントと統合できます。

2.1 Claude Desktop (Windows/macOS)

これは Serena MCP を無料で利用する最良の方法 です。Claude の無料プランでも利用できます。

1. Claude Desktop を開き、File / Settings / Developer / MCP Servers / Edit Config を選択。

2. claude_desktop_config.json が開くので、mcpServers に Serena MCP を追加します：

   uvx を使用した例：

   {
     "mcpServers": {
       "serena": {
         "command": "/abs/path/to/uvx",
         "args": [
           "--from",
           "git+https://github.com/oraios/serena",
           "serena",
           "start-mcp-server"
         ]
       }
     }
   }
   
   

3. 保存後、Claude Desktop を完全終了して再起動してください。

4. トラブルシューティング： Claude が Serena MCP を認識してもツールを呼び出さない場合、FileSystemMCP を無効にしてください（ツール名の競合が原因となることがあります）。

Windows WSL2 統合

Windows 上で Claude Desktop を実行し、Serena MCP を WSL2 (Ubuntu) 内にインストールしている場合、コマンドに wsl.exe -d Ubuntu を付けて実行してください。

2.2 Codex (OpenAI CLI)

Codex は MCP を完全にサポートしていないため、特別なコンテキストが必要です。

1. ~/.codex/config.toml に次を追加（ファイルが存在しない場合は作成）：

   [ mcp_servers . serena ]
   command = "uvx"
   args = [ "--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "codex" ]
   
   

   注意: --context codex を必ず指定してください。

2. 起動後にプロジェクトを有効化： Codex はグローバル設定のため、明示的にプロジェクトを有効化する必要があります：

   "Activate the current dir as project using serena"

3. トラブルシューティング： Codex ではツール実行が成功しても failed と表示されることがあります（既知のバグ）。

2.3 Claude Code Serena（CLI 統合）

プロジェクトディレクトリ内で、次のコマンドを使用して Claude Code Serena を追加できます：

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

これにより Claude Code Serena のワークフロー内で直接 Serena MCP が利用可能となり、シンボルレベルの編集やプロジェクト管理がシームレスに行えます。

2.4 その他の MCP クライアント (Cursor, Cline, Roo-Code, Windsurf)

Serena MCP は MCP サーバーとして動作するため、MCP 対応クライアント（IDE 拡張や VSCode ライクな IDE）と統合できます。

• 推奨: -context ide-assistant を args に必ず指定してください。
• コスト注意: これらのクライアントで Serena MCP を利用する場合、選択した LLM の API 料金 が発生します。

2.5 ローカル GUI とその他の LLM (Agno, OpenWebUI)

Serena MCP は Claude に限定されません。Agno, OpenWebUI, Jan などと組み合わせ、Gemini や ローカルモデル（Ollama/LM Studio） と統合できます。

• 非 Claude クライアントの場合、API Key が必要になるため追加コストが発生します。

---

3. 実際の利用とワークフロー

Serena MCP はファイル読み込みやテキスト検索ではなく、find_symbol（シンボル検索）や insert_after_symbol（シンボル後挿入）といった IDE レベルのツールを提供します。

3.1 プロジェクトの有効化とインデックス作成

Serena MCP のツールを使う前に、LLM にどのプロジェクトを扱うか知らせる必要があります。

• プロジェクト有効化:

  "Activate the project /path/to/my_project"

• 単一プロジェクト制限: Serena MCP は現時点で 1 つのプロジェクトのみ を処理可能です。

• インデックス作成: 大規模プロジェクトでは、インデックス化によりツール実行を高速化できます：

  uvx --from git+https://github.com/oraios/serena serena project index
  
  

3.2 初回利用：オンボーディングとメモリ

Serena MCP には独自のメモリシステムがあります。

• オンボーディング: 初回実行時、Serena MCP はプロジェクト構造・重要情報・ビジネスロジックを解析し、結果を .serena/memories/ ディレクトリに メモリファイル として保存します。
• メモリ利用: その後のセッションでは、LLM がこれらのファイルを選択的に読み込み、より正確なコンテキスト理解を実現します。
• オンボーディング回避: .serena/memories/ にダミーファイルを作成すればスキップ可能です。

3.3 コーディング、編集、自律エージェント動作

Serena MCP は高度なワークフローをサポートします。

• シンボルレベル編集: 正確な編集には replace_symbol_body を使用。
• 自動修正（エージェントループ）: execute_shell_command を有効化すると（Claude Desktop や Claude Code Serena ではデフォルト）、Serena MCP はコード実行・テストを行い 自律的にエラー修正 を行います。
• セキュリティ注意: 任意のコマンドを実行できるため、パラメータは必ず確認してください。分析のみの場合、read_only: true を設定してください。

3.4 コンテキスト超過の回避

長いタスクやコンテキスト上限に近づいた場合、新しい会話で継続するのが最適です。

• prepare_for_new_conversation: 現在の状態を要約しメモリに保存する専用ツールがあります。新しいセッションでこれを読み込めば、途切れなく続行可能です。

3.5 コンテキストとモードのカスタマイズ

Serena MCP の挙動は コンテキスト（Contexts） と モード（Modes） によって調整できます。

• コンテキスト: 起動時に設定。例：desktop-app（デフォルト）、agent（自律型）、ide-assistant（IDE 統合用、Claude Code Serena と好相性）。
• モード: タスク種類に応じて動的に切替可能（例：planning、editing、one-shot）。switch_modes ツールで切替できます。