---
title: "SerenaをClaude Code・Codex・Gemini CLIに統合する実践ガイド ― 設定・ツール運用・要否判断"
url: "https://www.issoh.co.jp/tech/details/8059/"
published: 2025-08-06
updated: 2026-09-27
categories: ["AIエージェント・MCP"]
publisher: "株式会社一創"
---

# SerenaをClaude Code・Codex・Gemini CLIに統合する実践ガイド ― 設定・ツール運用・要否判断

Serenaは、Oraiosが公開するオープンソース（MITライセンス）のコーディングエージェント向けツールキットで、コードを「行」ではなく関数・クラス・変数といった**シンボル単位**で検索・編集する機能をMCPサーバーとして提供する。裏側でLSP（Language Server Protocol）の言語サーバーを動かすため、grepや全文読み込みに頼るエージェントに、IDE相当のコード理解を後付けできる。本記事はSerenaの実践的な統合に絞り、Claude Code・Codex・Gemini CLIなどへの接続手順、`context`と`mode`による挙動制御、Docker運用、主要ツール、そして「そもそも入れるべきか」の判断までをまとめる。Serenaの定義や内部の仕組みを先に押さえたい場合は、[Serena MCPとは？仕組み・導入手順・Claude Code連携を実務目線で解説](/tech/details/8197/)を土台にしてほしい。

## まとめ：Serena統合の要点

- **前提はuvのみ。**導入は`uv tool install serena-agent`か、`uvx`でGitHubから直接起動する2通り。
- **Claude Codeへは`claude mcp add`一発。**`--context claude-code`で標準ツールと重複する機能を自動的に外す。
- **Codexは`serena setup codex`、VSCodeは`--context vscode`、Gemini CLI等は`--context ide`**と、クライアントごとにcontextを変えるのが要点。
- **`context`は起動時固定・ツール集合を決める。`mode`は途中で複数重ねられ、planning／editingなど作業スタイルを切り替える。**
- **効くのは大規模・多言語・シンボル横断のコードベース。**単一ファイルの小改修なら標準ツールで足り、Serenaはむしろ過剰になる。

以下、統合手順から順に見ていく。

## Serenaがコーディングエージェントにもたらす価値

大規模リポジトリでエージェントが失敗する典型は、関連ファイルを丸ごと読み込んでコンテキストを使い切る、あるいはgrepの文字列一致で見当違いの箇所を編集する、という2つだ。Serenaはこの2点をLSP由来のセマンティック操作で置き換える。

### 行単位ではなくシンボル単位で読む

Serenaは`get_symbols_overview`でファイルの構造（定義されている関数・クラスの一覧）だけを先に取り、`find_symbol`で目的の定義本体をピンポイントに読む。全文を読み込まないため、数千行のファイルでも消費トークンは定義1つ分に収まる。改修時は`find_referencing_symbols`で「この関数を呼んでいる箇所」を言語サーバー経由で正確に列挙できるため、文字列検索では拾えない参照漏れを防げる。ここがSerenaの中核価値で、コードベースが大きいほど差が開く。

### 対応言語と前提（LSP）

Serenaは40言語超に対応し、Python・TypeScript／JavaScript・Go・Rust・Java・C#・PHP・Ruby・C／C++などをカバーする。実体は各言語のLSPサーバーを起動して解析するため、対象言語のツールチェーンが利用できる環境が前提になる。逆に言えば、対応言語のプロジェクトであれば追加設定なしにシンボル解析が効く。

## Claude Codeへの統合手順

Serenaの利用者がもっとも多いのがClaude Codeとの組み合わせだ。手順は「前提のuv」「`claude mcp add`」「`serena init`と動作確認」の3つに分かれる。

### 前提：uvの用意とSerenaの入手

Serenaはパッケージマネージャ`uv`で管理される。必要な前提はuvのインストールだけで、Serena本体は次のいずれかで入手する。

```
// グローバルに常駐インストール
uv tool install -p 3.13 serena-agent

// もしくは都度GitHubから直接起動（インストール不要）
uvx --from git+https://github.com/oraios/serena serena start-mcp-server
```

前者はコマンドとして`serena`が使えるようになり、後者は常に最新のmainを取得して起動する。まず試すだけなら後者、恒常運用なら前者が扱いやすい。

### claude mcp add で登録する

Claude CodeへはCLIの`claude mcp add`で登録する。全プロジェクトで使うユーザースコープと、特定プロジェクト限定の2通りがある。

```
// 全プロジェクト共通（ユーザースコープ）
claude mcp add --scope user serena -- serena start-mcp-server --context claude-code --project-from-cwd

// このプロジェクトだけに登録
claude mcp add serena -- serena start-mcp-server --context claude-code --project "$(pwd)"
```

ポイントは`--context claude-code`を指定すること。これによりClaude Codeが標準で持つファイル読み書きやシェル実行と重複するツールが自動的に無効化され、ツール一覧の肥大とトークン浪費を避けられる。対象プロジェクトは`--project-from-cwd`で起動時のカレントディレクトリから自動判定するか、`--project`でパスを明示する。加えて公式は、モデルがSerenaのツールを使い渋る場合の対策として`serena prompts print-cc-system-prompt-override`の出力をCLAUDE.mdへ追記することを勧めている。

### serena init と動作確認

登録後、対象プロジェクトで`serena init`を実行すると初期化と設定の妥当性チェックが走る。起動中はSerenaが既定で`http://localhost:24282/dashboard/index.html`にWebダッシュボードをたてる。ここでツールの呼び出しログ・設定・稼働状態を確認でき、エージェントがどのツールをどう使ったかを追える。ポート24282が使用中なら番号が繰り上がる。Claude Code側で`/mcp`を確認しserenaが接続済みになっていれば統合完了だ。

## Codex・Gemini CLI・VSCodeへの統合

SerenaはClaude Code専用ではなく、MCP対応のコーディングエージェント全般に接続できる。クライアントごとに適切な`context`を選ぶのが唯一のコツで、標準機能の重複を避けるために使い分ける。

### Codex

Codexはセットアップ用のサブコマンドが用意されており、`serena setup codex`を実行すれば設定ファイル（`~/.codex/config.toml`）へserenaサーバーのエントリが追加される。手動で同ファイルにMCPサーバー定義を書いても同じ結果になる。SerenaはClaude Code専用ではなく、OpenAIのCodexでシンボル解析を効かせたい需要にも同じ流儀で対応できる。

### Gemini CLI・VSCode・Cursor

VSCode向けには`--context vscode`を、Gemini CLIやCursor・Clineのような「自前でファイル操作やシェル実行を持つ」エージェントには汎用の`--context ide`を指定する。いずれもクライアント側が既に備える機能とSerenaのツールが二重化しないよう、公開ツールを絞る狙いがある。VSCodeでワークスペース単位に紐付けるなら`--project ${workspaceFolder}`を併用する。

## contextとmodeで挙動を制御する

Serenaの運用で最初に理解しておきたいのが`context`と`mode`の違いだ。両者を取り違えると「ツールが出てこない」「オンボーディングが毎回走る」といった詰まり方をする。

### context：起動時に固定する動作環境

`context`はSerenaがどのクライアント環境で動くかを表し、初期システムプロンプトと公開ツール集合を決める。**起動時に決まり、セッション中は変更できない。**主なものは次の通り。

| context     | 用途                                  |
| ----------- | ----------------------------------- |
| desktop-app | 既定。Claude Desktop等。全ツールを公開          |
| claude-code | Claude Code標準と重複するツールを無効化           |
| ide         | Cursor/Cline/Gemini CLI等の汎用エージェント向け |
| vscode      | VSCode専用（ワークスペース連携）                 |
| codex       | Codex向け                             |
| agent       | エージェントスクリプトから直接動かす場合                |

Claude Codeで全ツールが出てしまいツール数が膨らむときは、`--context claude-code`の付け忘れを疑うとよい。

### mode：作業スタイルを重ねる可変設定

`mode`は特定の作業に向けて振る舞いを調整するフラグメントで、**複数を同時に有効化できる**。planning（分析・計画重視）、editing（直接編集向け）、interactive（対話的な往復）、one-shot（単発完結）、no-onboarding（オンボーディング省略）、onboarding、no-memories（メモリツール無効）、query-projects（他プロジェクト横断）などがある。たとえば計画立案では`planning`、機械的な一括修正では`editing`＋`one-shot`のように重ねる。ただし`interactive`と`one-shot`は意味的に両立しないため、同時指定は避ける（Serena側では自動排他されない）。

### Docker・uvxでの起動方法

ローカルに直接入れず隔離環境で動かしたい場合はDockerを使う。ここで注意点があり、標準の`stdio`トランスポートはSerenaがクライアントの直接の子プロセスである前提のため、コンテナ内では`--transport sse`でネットワーク越しに接続する。ダッシュボード用にポート24282を公開し、環境変数`SERENA_DOCKER=1`を渡す構成が公式のDOCKER.mdで示されている。Docker周りは変更が入りやすいので、実際のオプションは公式のDOCKER.mdで最新を確認してほしい。単一マシンでの通常利用なら、前述の`uvx`直接起動のほうが手数は少ない。

## 主要ツールとpermissions・セキュリティ設定

Serenaが公開するツールは多いが、実務で意識するのは検索系・編集系・シェル実行・メモリの4系統に絞られる。権限の考え方も合わせて押さえておく。

### 押さえておく主要ツール

| 系統 | ツール                                            | 役割             |
| -- | ---------------------------------------------- | -------------- |
| 把握 | get\_symbols\_overview                         | ファイルの定義一覧を取得   |
| 検索 | find\_symbol / find\_referencing\_symbols      | 定義の特定／参照元の列挙   |
| 検索 | search\_for\_pattern                           | 正規表現でのパターン検索   |
| 編集 | replace\_symbol\_body                          | シンボル本体の置換      |
| 編集 | insert\_after\_symbol / insert\_before\_symbol | 指定シンボルの前後へ挿入   |
| 実行 | execute\_shell\_command                        | テスト・ビルド等の実行    |
| 記憶 | write\_memory / read\_memory                   | プロジェクト知識の保存・参照 |

rename（シンボル改名）やmoveなど一部のリファクタリング系ツールはJetBrainsプラグイン版でのみ提供される点に注意する。標準のMCPサーバーでは上表の編集ツールを組み合わせて改修するのが基本形になる。

### execute\_shell\_commandと権限の絞り込み

Serenaの警戒すべきツールは`execute_shell_command`だ。エージェントが任意のシェルコマンドを実行できるため、信頼できないコードベースや共有環境ではこれが攻撃面になる。実行させたくない場面では読み取り・分析中心の`planning`系運用にとどめる、あるいはClaude Code側で`--context claude-code`を使い、シェル実行をClaude Code本体の権限管理（許可・拒否のプロンプト）に一本化する、といった切り分けが有効だ。

### .serena設定とメモリ・オンボーディング

初回の`serena init`／オンボーディングで、プロジェクト直下に`.serena`設定とメモリが作られる。メモリはエージェントがプロジェクト固有の知識（構成・命名規約など）を`write_memory`で残し次回以降`read_memory`で読み戻す仕組みで、毎回ゼロから探索し直す無駄を減らす。メモリ機能が不要なセッションでは`no-memories`モードで無効化できる。`.serena`はリポジトリにコミットするか各自ローカルに置くかを運用方針として決めておくとよい。

## Serena MCPは本当に必要か（使うべき場面・不要な場面）

「Serena MCPは不要では」という声はSERPでも一定数あり、Claude Code標準ツールの成熟に伴って議論が続いている。結論を先に言えば、**Serenaが効くかどうかはコードベースの規模と横断性で決まる。**

入れる価値が高いのは、数万行超・複数言語・モジュール間の依存が入り組んだリポジトリだ。全文読み込みではコンテキストが破綻し、grepでは参照追跡が不正確になる領域で、シンボル単位の検索・参照列挙・置換が精度とトークン効率の両方を押し上げる。既存の大規模コードの改修やリファクタリングが主戦場なら、導入コストを上回る。

一方、単一ファイル・数百行規模の小改修や、新規ファイルをゼロから書く作業では、Claude Codeなど標準ツールの読み書きで十分で、Serenaを足しても**ツール一覧が増えてかえってトークンを消費する**だけになりやすい。「価値を感じない」という体験の多くは、対象が小さいか、`--context claude-code`を付けずに標準ツールと二重化しているケースだ。まず小さく試し、大規模リポジトリで参照追跡や横断改修に効くと感じてから常用へ広げる、という順序が現実的な判断になる。

## よくある質問

### serena init は何をするコマンドですか？

プロジェクトの初期化とセットアップの妥当性チェックを行うコマンドで、`.serena`設定やオンボーディングの起点になる。登録直後に対象プロジェクトで実行し、ダッシュボードやClaude Codeの`/mcp`で接続を確認する。サブコマンドはバージョンで変わることがあるため、最新は公式ドキュメントで確認するとよい。

### Serena（MCP）は無料で使えますか？

SerenaはMITライセンスのオープンソースで、ソフトウェア自体は無料で利用できる。追加費用がかかるのは接続先のエージェント（Claude Code等）側の利用料であって、Serenaの導入・運用に別途ライセンス料は発生しない。

### Claude Codeの標準ツールだけで足り、Serenaは不要ではありませんか？

小規模・単一ファイル中心の作業なら標準ツールで足り、Serenaは過剰になりやすい。効果が出るのは大規模・多言語・参照が横断するコードベースで、シンボル単位の検索・置換がトークン効率と精度を上げる場面だ。導入するなら`--context claude-code`でツールの二重化を避けるのが前提になる。

### git worktreeと併用できますか？

Serenaはプロジェクトのディレクトリを対象に動くため、worktreeで切り出した作業ツリーをそのまま`--project`やカレントディレクトリとして指定すれば併用できる。ブランチごとにツリーを分けて並行作業する運用でも、各ツリーで個別にSerenaを起動すれば干渉しない。

### どのプログラミング言語に対応していますか？

Python・TypeScript／JavaScript・Go・Rust・Java・C#・PHP・Ruby・C／C++など40言語超に対応する。各言語のLSPサーバーを起動して解析するため、対象言語の開発環境が使える前提であればシンボル解析が有効になる。

## 関連記事

- [Serena MCPとは？仕組み・導入手順・Claude Code連携を実務目線で解説](/tech/details/8197/)
- [Claude Codeとは？できること・使い方・料金とコード解析の実力【2026年版】](/tech/details/5571/)
- [FastMCPとは｜PythonでMCPサーバーを最速構築するフレームワークの使い方【2026年版】](/tech/details/6507/)

---

出典: [SerenaをClaude Code・Codex・Gemini CLIに統合する実践ガイド ― 設定・ツール運用・要否判断](<https://www.issoh.co.jp/tech/details/8059/>)（株式会社一創）