--- title: "Serena MCPとは？仕組み・導入手順とv2の変更点（REPL・GPL化）" url: "https://www.issoh.co.jp/tech/details/8197/" published: 2025-08-14 updated: 2026-10-20 categories: ["AIエージェント・MCP"] publisher: "株式会社一創" --- # Serena MCPとは？仕組み・導入手順とv2の変更点（REPL・GPL化） Serena MCP（セレナ）は、ドイツのOraios AIが開発するオープンソースのMCPサーバーで、言語サーバー（LSP）を使ってコードを**関数・クラスなどのシンボル単位**で検索・編集する道具をAIエージェントに渡します。2026年10月13日のv2.0.0で、アプリ本体のライセンスがMITからGPL-3.0-or-laterに変わり、新規に初期化した設定では操作の窓口が「Pythonコードを実行するREPL」になりました。最新版はv2.1.0（2026年10月19日）です。この記事では、仕組み・インストール・Claude Codeへの登録に加え、v2.1.0を実際に起動して確かめたツール構成と、ネット上に残る古い手順の誤りを整理します。 ## まとめ：Serena MCPの要点（v2.1.0時点） - **正体**：LSPでコードをシンボル単位に扱うMCPサーバー。Claude Code・Codex・Cursor・JetBrains系IDEなどMCP対応クライアントから使う。 - **料金**：本体は無料。前提は`uv`だけ。JetBrainsプラグイン版のバックエンドのみ有料（無料試用あり）。 - **ライセンス**：v2以降の本体はGPL-3.0-or-later。社内利用だけならソース提供義務は通常生じないが、社外へ配布する場合はGPLに従ったソース提供などが必要。v1.7.0までは引き続きMIT。 - **導入**：`uv tool install -p 3.13 serena-agent`→`serena init`→`serena setup claude-code`の3コマンド。 - **v2で新規に初期化するとREPL方式**：公開されるMCPツールは`serena_repl`など2〜3個に減る。v1から更新しただけの設定はtools方式のまま。シェル実行や書き込みを確実に禁じたいなら、tools方式に戻して`excluded_tools`で外す。 ## Serena MCPとは：LSPでコードを扱うMCPサーバー 公式READMEは、Serenaを「IDEに近いシンボル単位の検索・編集・リファクタリング・デバッグの道具を、MCP経由で任意のクライアントとLLMに提供するもの」と説明しています。行番号や文字列一致ではなく「このメソッドの定義」「このクラスを参照している箇所」という単位で操作するため、大きなリポジトリでもAIが読む範囲を絞れます。[GitHubのoraios/serena](https://github.com/oraios/serena)は2026年10月20日時点でスター数が約3万400です。MCPそのものの仕組みは[MCPとは？AIと外部ツールをつなぐ標準規格とMCPサーバーの仕組み・作り方を解説](/column/details/12966/)で扱っています。 ### 開発元・料金・ライセンス（v2でGPL-3.0へ変更） 開発元はOraios AI（Jain & Panchenko IT-Berater Partnerschaft）で、PyPIのパッケージ名は`serena-agent`です。本体の利用は無料で、Serena自体のアカウント登録やAPIキーはいりません。費用がかかるのは、Serenaを呼び出すClaude CodeやCodexなどのエージェント側です。 ライセンスはGPLv2、MIT、GPL-3.0-or-laterの順に2回変更されています。[リポジトリのLICENSE](https://github.com/oraios/serena/blob/main/LICENSE)によると、当初はGPLv2で、2025年5月1日にMITへ変更、v2（2026年10月13日）からアプリ本体がGPL-3.0-or-laterになりました。言語サーバーとの通信層であるSolidLSP（`src/solidlsp`）はMITのままで、両者を同梱する`serena-agent`パッケージ全体はGPLの条件に従います。変更は遡及せず、MITで出た最後の版はv1.7.0です。 - **手元で使うだけ**：GPLは配布時の義務を定めるもので、社内の開発端末で使う分には実務上の制約はほぼない。 - **社外へ配布する**：改変版をGPLの条件で配布し、配布形態に応じて対応するソースを受領者が入手できるようにする必要がある。不特定多数への一般公開が一律に必要なわけではない。自社製品へ組み込んで配布する計画があるなら法務確認が先。 - **コントリビュート**：v2からCLA（コントリビューター同意書）への同意が必須。 ### 対応言語と2つのバックエンド（言語サーバー／JetBrainsプラグイン） コード解析の土台は2種類から選びます。既定は無料の言語サーバー（LSP）方式で、READMEはPython・TypeScript・Go・Rust・Java・C#・PHP・Kotlin・Swift・Terraform・VB.NET（v2.1.0で追加）など40言語超を挙げています。もう1つは有料の[Serena JetBrains Plugin](https://oraios.github.io/serena/02-usage/025%5Fjetbrains%5Fplugin.html)で、IntelliJ IDEAやPyCharmの解析機能を使います（RiderとCLionは非対応）。初期化時に`serena init -b JetBrains`と指定すると切り替わります。 | 機能 | 言語サーバー（無料） | JetBrainsプラグイン（有料） | | ----------- | ---------- | ------------------ | | シンボル検索・参照検索 | 対応 | 対応 | | リネーム | シンボルのみ | シンボル・ファイル・ディレクトリ | | 移動・インライン化 | 非対応 | 対応 | | 型階層・依存先の検索 | 非対応 | 対応 | | デバッガ操作 | 非対応 | 対応 | JetBrains IDEを常用していて移動やインライン化までAIに任せたいならプラグイン、それ以外は言語サーバー方式で十分です。 ## Serena MCPの仕組み：シンボル単位の検索と2つのインターフェース Serenaは各言語の言語サーバーを裏で起動し、そこから得たシンボル情報をMCPのツールとしてエージェントに返します。エージェントが「`Cart.total`を書き換えて」と考えたとき、ファイル全体を読む代わりに定義の範囲だけを取り出し、その範囲を差し替えます。 ### grep・全文読み込みとの違い | 方式 | AIが読む量 | 他ファイルの参照 | 向く作業 | | -------------- | --------- | --------- | ------------- | | Serena（シンボル単位） | 定義と参照箇所のみ | 言語サーバーが解決 | 多ファイルのリネーム・改修 | | grep・正規表現 | 一致行と前後 | 文字列一致のみ | 単純な置換・ログ調査 | | ファイル全体の読み込み | ファイル全体 | 読んだ範囲のみ | 小さなファイルの編集 | 公式はトークン削減率を数値で公表していません。READMEにあるのは、Claude Code上のモデルに約20の作業をさせて感想を集めた評価で、「慎重にやれば8〜12手順かかるファイル横断のリネームや参照検索が1回の呼び出しで済む」という定性的な結果です。 ### v2の新インターフェース「REPL」とtools方式の違い v2では、エージェントがSerenaを呼ぶ窓口が2種類になりました。従来の**tools方式**は操作ごとに1つのMCPツールを公開し、新しい**REPL方式**は`serena_repl`という1つのツールでPythonコードを実行させ、その中で`s.lsp.find_symbol(...)`のように各操作を呼びます。[公式のTools and APIs](https://oraios.github.io/serena/01-about/035%5Ftools.html)は、複数の操作を1回の呼び出しにまとめられ、途中結果を会話に流さずに済む点を利点に挙げています。`serena init`が作る`serena_config.yml`の既定値は`agent_interface: REPL`です。 この差がクライアントからどう見えるかを確かめるため、2026年10月20日にmacOS上でserena-agent 2.1.0を`uvx`で起動し、MCPの`tools/list`応答を取得しました。対象は3ファイルのPythonプロジェクトで、表の文字数は応答のtools配列をJSON文字列にしたときの長さです（トークン数ではありません）。 | context | 方式 | 公開ツール数 | ツール定義の文字数 | | ----------- | ----- | ------ | --------- | | claude-code | REPL | 2 | 4,394 | | claude-code | tools | 21 | 26,274 | | ide | tools | 22 | 32,011 | | desktop-app | tools | 29 | 39,475 | 同じclaude-codeでも、今回の測定ではtools方式のツール定義文字数はREPL方式の約6倍でした。この比率は、会話全体のトークン消費量の比率を示すものではありません。tools方式のclaude-codeでは`read_file`・`search_for_pattern`・`execute_shell_command`が外れていて、Claude Code自身の読み込み・検索・シェルと重複しない構成になっていました。会話の文脈を節約したいならREPL、どのツールが呼ばれたかを1件ずつ確認したいならtools方式、という選び方になります。なお、v2でセッションIDをSerena側で管理するようになったのは、[MCP Python SDK v2 移行：FastMCPからMCPServerへの書き換え手順と据え置き判断](/tech/details/18273/)で触れたSDK v2の変更に合わせたものです。 ## Serena MCPでできること：主要ツール一覧 tools方式で既定で有効になるツールは、`serena tools list`で数えると29個でした（任意ツールを含めた公式一覧は50以上）。REPL方式でも同じ操作を`s.lsp`などの窓口から呼べます。 - **検索**：`find_symbol`（シンボル検索）、`find_referencing_symbols`（参照元の一覧）、`get_symbols_overview`（ファイルの構造）、`find_declaration`・`find_implementations`、`get_diagnostics_for_file`（エラー・警告） - **編集**：`replace_symbol_body`（定義の差し替え）、`insert_after_symbol`・`insert_before_symbol`、`replace_content`、`replace_in_files`（複数ファイル一括置換・事前プレビュー付き） - **リファクタ**：`rename_symbol`、`safe_delete_symbol`（参照が残っていないか確認して削除） - **メモリ**：`write_memory`・`read_memory`・`edit_memory`など。プロジェクトの知識を`.serena/memories/`に残し、次回のセッションへ引き継ぐ - **初回処理**：`onboarding`（構成やビルド・テスト手順を調べてメモリへ保存）、`initial_instructions` ## Serena MCPのインストール手順（uv・serena init） 前提は[uv](https://docs.astral.sh/uv/getting-started/installation/)のインストールで、Python本体もuvが用意します。ただし、LSP方式では対象言語によって追加の依存ソフトウェアが必要です。 ### uvによるSerenaのインストールと初期化 ``` uv tool install -p 3.13 serena-agent serena init serena --version # Serena 2.1.0 ``` `serena init`は`~/.serena/serena_config.yml`を作り、PATH上にClaude CodeやCodexがあれば「`serena setup claude-code`」「`serena setup codex`」を実行するよう案内します。今回の環境ではこの2行が表示されました。更新は`uv tool upgrade serena-agent`です。インストールせずに試すなら、`uvx -p 3.13 --from git+https://github.com/oraios/serena serena start-mcp-server`で起動できます。 ### プロジェクトの登録とインデックス作成 大きなリポジトリでは、最初のシンボル検索で待たされないよう、[公式のProject Workflow](https://oraios.github.io/serena/02-usage/040%5Fworkflow.html)が事前のインデックス作成を勧めています。JetBrainsプラグイン版ではIDEが索引を持つため不要です。 ``` cd /path/to/your-project serena project create --index . ``` 3ファイルの検証用プロジェクトでは、言語（python）が自動判定され、`.serena/project.yml`・`.serena/cache/`・`.serena/memories/`が作られました。所要時間はuvxの起動を含めて約12秒でした。登録済みのプロジェクトは`serena project index`で索引を作れます。索引作成は1回でよく、その後はファイルの変更に合わせてSerenaが自動で更新します。登録の解除はv2で追加された`serena project remove`です。 ### Serena v2.1.0に存在しないコマンドと代替手順 検索上位の解説には、v2.1.0に存在しないコマンドを載せたものがあります。実行すると次のようになります。 | 見かける記述 | v2.1.0での結果 | 正しい手順 | | ------------------------ | ----------------- | -------------------------------------- | | `pip install serena-mcp` | PyPIにパッケージなし（404） | `uv tool install -p 3.13 serena-agent` | | `serena index` | No such command | `serena project index` | | `serena run` | No such command | `serena start-mcp-server` | | `serena info` | No such command | `serena --version` | 公式READMEも「MCPやプラグインのマーケットプレイス経由で入れないこと。古く最適でない起動コマンドが載っている」と注意しています。 ## Claude CodeでSerena MCPを使う設定 ### Claude Codeへの登録コマンド v2では`serena setup claude-code`の1行で登録できます。手動で登録する場合、[公式のクライアント接続ガイド](https://oraios.github.io/serena/02-usage/030%5Fclients.html)は次の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)" ``` Claude Code内で`/mcp`を実行して接続を確認し、起動が間に合わない場合は環境変数`MCP_TIMEOUT=60000`を設定します。長いセッションでSerenaのツールが使われなくなる対策として、公式は`serena-hooks`を使うフック設定（`remind`・`activate`など）も用意しています。CodexやGemini CLIを含む統合の詳細と運用は[SerenaをClaude Code・Codex・Gemini CLIに統合する実践ガイド](/tech/details/8059/)にまとめました。 ### contextとmodeの選び方（v2.1.0の一覧） `--context`は接続先クライアントに合わせたツール構成、`--mode`はその上に重ねる振る舞いです。v2.1.0の`serena context list`と`serena mode list`の出力から、contextのテンプレート項目を除いた一覧は次のとおりです。 - **context（16種）**：agent、antigravity、chatgpt、claude-code、codebuddy、codex、copilot-cli、desktop-app（既定）、grok、ide、jb-ai-assistant、jb-copilot-plugin、junie、oaicompat-agent、vscode、zcode - **mode（9種）**：benchmark、editing、interactive、no-memories、no-onboarding、onboarding、one-shot、planning、query-projects Claude Codeなら`claude-code`、CursorやClineなど汎用IDEなら`ide`、VS CodeのCopilotなら`vscode`を選びます。既定のmodeはeditingとinteractiveの2つでした。 ### Webダッシュボードの接続先と起動設定 Serenaは起動時にWebダッシュボードを開き、ログ・セッション・ツールの使用状況を表示します。既定のURLは`http://localhost:24282/dashboard/`で、複数起動すると24283以降に移ります。v2.1.0からは初回に「起動のたびに開くか」を選ぶ画面が出て、`web_dashboard_open_on_launch`に保存されます。 ## Serena MCPの安全設計：REPLの制限とサンドボックス [公式のSecurityページ](https://oraios.github.io/serena/02-usage/070%5Fsecurity.html)は、手元のマシン・MCPクライアント（LLM）・作業対象のリポジトリをすべて信頼できる前提で設計していると明記し、意図しない操作を完全に防ぐ手段はサンドボックスだけだとしています。導入前に押さえる点は3つです。 - **REPL方式では制限が保証されない**：tools方式なら`excluded_tools`に`execute_shell_command`を入れればシェル実行は消える。REPL方式では実行されるPythonコードがSerenaのプロセスでできることを何でもできるため、操作の除外も`.serena/project.yml`の`read_only: true`も書き込みを止める保証にならない。 - **信頼済みプロジェクト**：`trusted_project_path_patterns`に一致しないプロジェクトでは、起動時コマンドや言語サーバー設定の上書き、プロジェクト外へのシンボリックリンク追跡が無効になる。v2.1.0では、未信頼のリポジトリを開いただけでその中の`tsserver.js`が実行される問題も塞がれた。 - **隔離はDockerで**：公式は必要なファイルだけを見せたDockerコンテナでの実行を勧めている。 社内リポジトリでシェル実行を禁じたいなら、`agent_interface: tools`に戻したうえで`excluded_tools`を設定するのが確実です。Claude Code側の許可ルールやサンドボックスの設定は[Claude Codeのセキュリティ設定｜権限ルール・サンドボックス・管理設定で守る実装手順【2026年10月】](/tech/details/18080/)を参照してください。 ## Serena MCPが不要なケースと導入の判断基準 Serenaが効くのは、読む量を減らす余地が大きいときです。次に当てはまるなら入れなくてかまいません。 - **数ファイルの小さなプロジェクト**：クライアント標準の読み込みで足り、言語サーバーの起動とインデックス作成のほうが手間になる。 - **言語サーバーが弱い言語・独自DSL**：シンボル解析が効かず、テキスト検索と変わらなくなる。 - **一度きりの修正**：オンボーディングやメモリの蓄積が回収できない。 逆に、複数モジュールにまたがるリネームや参照調査を日常的にAIへ任せている、あるいはJetBrains IDEで移動・インライン化まで自動化したいなら入れる価値があります。エージェントを社内の開発基盤へ組み込む設計から相談したい場合は、[AIエージェント開発](/service/ai/agent/)の支援内容も参考にしてください。 ## よくある質問 ### Serena MCPの読み方は？ 「セレナ」と読みます。検索では「セレナmcp」「serenamcp」と表記がゆれますが、すべてOraios AIのoraios/serenaを指します。 ### Serena MCPは無料ですか？商用利用できますか？ 本体は無料で、業務での利用もできます。v2からGPL-3.0-or-laterになったため、社外へ配布する場合は、改変の有無や配布形態に応じてGPLの条件を満たし、対応するソースを受領者が入手できるようにする必要があります。有料なのはJetBrainsプラグイン版のバックエンドと、Serenaを呼び出すエージェント側の利用料です。 ### Serena MCPをアップデートするには？ `uv tool install`で入れた場合は`uv tool upgrade serena-agent`を実行し、`serena --version`で版を確認します。新規設定ではREPLが既定ですが、旧設定に`agent_interface`がない場合は互換性のためtools方式が維持されます。tools方式を明示するには`serena_config.yml`の`agent_interface`を`tools`にします。 ### Claude Code以外でも使えますか？ 使えます。Codex（`serena setup codex`）、Cursor・Cline、VS CodeのCopilot、JetBrains AI Assistant、Junie、Claude Desktopなど、MCPに対応したクライアントなら接続でき、`--context`を接続先に合わせて指定します。 ### インストールにPythonの準備は必要ですか？ 不要です。前提はuvだけで、`-p 3.13`の指定どおりuvがPython 3.13を用意します。PyPIの`serena-agent` 2.1.0が対応するのはPython 3.11以上3.15未満です。 ## 関連記事 - [SerenaをClaude Code・Codex・Gemini CLIに統合する実践ガイド ― 設定・ツール運用・要否判断](/tech/details/8059/) - [MCPとは？AIと外部ツールをつなぐ標準規格とMCPサーバーの仕組み・作り方を解説](/column/details/12966/) - [Claude Codeのセキュリティ設定｜権限ルール・サンドボックス・管理設定で守る実装手順【2026年10月】](/tech/details/18080/) - [FastMCPとは？PythonでMCPサーバーを作る手順とFastMCP 4.1の使い方【2026年10月】](/tech/details/6507/) - [【2026年最新】Claude Codeのおすすめ拡張機能6つを役割別に整理｜プラグインとの違い・使い分けを解説](/tech/details/10463/) --- 出典: [Serena MCPとは？仕組み・導入手順とv2の変更点（REPL・GPL化）]()（株式会社一創）