VScode + Gemini CLI に Serena を導入

Last updated at 2025-08-06Posted at 2025-08-06

本記事の作成も含めて、 Serena の導入に関するほとんどの作業を、Gemini CLI の YOLO mode で実行しました。

はじめに

このガイドでは、ターミナルから実行するコマンドライン版のGemini CLIとSerena MCPを連携させ、その機能を最大限に活用する方法について解説します。VSCodeとの連携についても触れますが、本記事の主眼はCLI環境でのSerena活用にあります。

これまでは、Googleドキュメントなどを用いて音声入力を行い、そのテキストをチャット欄に貼り付けるという手間があり、同時に、ターミナル、ファイルをチェックするためのファイラー、そして別のターミナルウィンドウへの移動など、複数のアプリケーションやウィンドウを行き来する必要がありました。

しかし、VS Codeの統合ターミナルでGemini CLIを実行し、左側に音声入力用のテキストエディタ、右側にGemini CLIのターミナルを配置することで、音声入力からAIとの対話、そして結果の確認までをシームレスに行えるようになりました。

これにより、開発ワークフローが大幅に効率化され、より直感的な操作が可能になります。Gemini CLI自身も、日々の作業をサポートするために、新しい知識や技術を学び続けています。

Serena MCPを導入することで、Gemini CLIのコード理解能力が向上し、より賢く、的確なアシスタンスを提供できるようになります。

環境

OS: Linux (Debian GNU/Linux 12 bookworm)
Gemini CLI バージョン: 0.1.18
作業ディレクトリ: $HOME/gemini_workspace

Serena MCPとは？

Serena MCP (Multi-Client Protocol) は、LLM (大規模言語モデル) を賢いコーディングエージェントにするためのオープンソースのツールキットです。LSP (Language Server Protocol) を利用してコードの構造やシンボルを深く理解し、LLMの能力を拡張します。これにより、Gemini CLIは以下のメリットを享受できます。

コードへの深い理解と正確性: コードの構造やシンボルを深く理解できるため、より正確な結果を出せる。
より賢い操作: 特定のブロックの効率的な読み込みや、コードの文脈を理解した上でのシェルコマンド実行など、より賢い操作が可能になる。
将来の複雑なタスクへの対応力: find_symbolやreplace_regexのような高度なツールを活用することで、複雑なリファクタリングや機能追加にもスムーズに対応できるようになる。

導入プロセス

本記事に記載されている情報は、特定の環境下での成功事例に基づいています。お使いの環境や設定によっては、記載通りの動作を保証するものではありません。導入の際は、ご自身の責任において実施してください。

成功したインストール手順

Serena MCPの導入は、主にpipxとuvパッケージマネージャーを使用して行います。

pipxのインストール:
pipxがシステムにインストールされていない場合、以下のコマンドでインストールします。
```
sudo apt install pipx
```
uvとuvxのインストール:
pipxを使用してuvパッケージマネージャーをインストールします。uvxコマンドも同時に利用可能になります。
```
pipx install uv
```
Serena MCPサーバーの起動:
uvxコマンドを使用してSerena MCPサーバーを起動します。
```
uvx --from git+https://github.com/oraios/serena serena start-mcp-server
```
Gemini CLI settings.jsonの設定 (Serena MCPサーバーへの接続設定):
Gemini CLIがSerena MCPサーバーに接続できるように、~/.gemini/settings.jsonファイルにmcpServersの設定を追加します。

この設定は、Gemini CLIがどのSerena MCPサーバーと通信するかを定義するものです。プロジェクトの認識は、Gemini CLIが実行されている現在のディレクトリに基づいてSerena MCPサーバー側で行われます。

設定例:
```
{
  "theme": "Default",
  "selectedAuthType": "oauth-personal",
  "hideBanner": "true",
  "enableToolSummaries": true,
  "ide": {
    "enabled": true
  },
  "preferredEditor": "vscode",
  "ideMode": false,
  "mcpServers": {
    "serena": {
      "command": "/home/YOUR_USERNAME/.local/bin/uvx",
      "args": ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--enable-web-dashboard", "false"]
    }
  }
}
```
注意: 上記のYOUR_USERNAMEの部分は、あなたの実際のユーザー名に置き換えてください。また、commandのパスはuvxのインストール場所によって異なる場合があります。

直面した課題と解決策

導入プロセス中にいくつかの課題に直面しましたが、これらは適切に解決されました。

uvxコマンドの初期エラー:
uvxコマンドが最初に見つからなかったため、uvパッケージマネージャーのインストールが必要でした。
pip install uvのエラー:
pip install uvを実行した際にexternally-managed-environmentエラーが発生しました。

これは、システムPython環境への直接的なパッケージインストールが推奨されないためです。pipxを使用することでこの問題を回避し、独立した環境でuvをインストールできました。
Gemini CLIの再起動:
settings.jsonの変更をGemini CLIに反映させるためには、Gemini CLIの再起動が必要です。設定変更後に「No MCP servers configured.」というメッセージが表示された場合、再起動が不足している可能性があります。
プロジェクトが認識されない問題:
Serena MCPサーバーが起動していても、Gemini CLIがプロジェクトを正しく認識しない場合があります。これは、Serenaがプロジェクトのルートディレクトリを特定できていない場合に発生します。

この問題は、Gemini CLIを再起動するか、Serena MCPサーバーのログを確認することで解決できる場合があります。

今回のケースでは、Gemini CLIが動作しているディレクトリ（$HOME/gemini_workspace）がSerenaによってプロジェクトのルートディレクトリとして認識されました。

これは、settings.jsonでの設定とGemini CLIの再起動により、Serenaがこのディレクトリをプロジェクトとして扱うようになったためです。

ブラウザ自動表示の停止

Serena MCPサーバー起動時に自動でブラウザが開くのを停止するには、settings.jsonのmcpServers設定にargsオプションを追加します。

{
  "mcpServers": [
    {
      "url": "http://localhost:8080",
      "name": "serena-mcp",
      "args": ["--enable-web-dashboard", "false"]
    }
  ]
}

Serenaツールの活用

Serena MCPを導入することで、Gemini CLIはより高度でインテリジェントなファイル操作、コード検索、そしてシンボルレベルでのコード編集が可能になります。これは、従来のGemini CLIのdefault_apiツールと比較して、以下のような明確な利点を提供します。

ファイル操作とシェルコマンド

ファイルの読み込み (serena.read_file vs default_api.read_file):
serena.read_fileは、ファイル全体だけでなく、特定の行範囲（チャンク）を指定して読み込むことができます。

これにより、大規模なファイルから必要な部分だけを効率的に取得し、Gemini CLIがより関連性の高い情報に集中できるようになります。default_api.read_fileも行範囲指定が可能ですが、serena.read_fileはLSPとの連携により、コードの文脈をより深く理解した上での読み込みが可能です。
シェルコマンドの実行 (serena.execute_shell_command vs default_api.run_shell_command):
serena.execute_shell_commandは、default_api.run_shell_commandと同様にシェルコマンドを実行しますが、SerenaのLSP統合により、コマンドの実行結果がコードの文脈とより密接に結びつき、より賢い判断をGemini CLIが下せるようになります。

例えば、ビルドコマンドの実行結果からエラー箇所を特定しやすくなります。

コード検索とシンボル操作

コード検索 (serena.search_for_pattern vs default_api.search_file_content):
serena.search_for_patternは、正規表現による柔軟なパターン検索に加え、検索結果の前後に行コンテキストを含めることができます。
また、restrict_search_to_code_filesオプションを使用することで、コードファイルに限定した検索が可能になり、より的確な検索結果を得られます。default_api.search_file_contentも正規表現検索をサポートしますが、コンテキスト行の指定やコードファイルに限定する機能はありません。
シンボル操作 (Serena独自の強力な機能):
default_apiには存在しないSerena独自のツール群が、コードのシンボルレベルでの操作を可能にします。

これにより、Gemini CLIは単なるテキスト置換を超えた、構造的なコード編集を実行できます。
- find_symbol: クラス、メソッド、変数などの特定のコードシンボルを名前パスで検索し、その定義場所を正確に特定します。
- find_referencing_symbols: 特定のシンボルがコードのどこで参照されているかを検索し、影響範囲を把握するのに役立ちます。
- replace_symbol_body: 特定のシンボルの本体（実装コード）を置き換えます。
- insert_after_symbol / insert_before_symbol: 特定のシンボルの定義の前後に新しいコードを挿入します。
- replace_regex: 正規表現による強力なテキスト置換ツールで、複数行にわたる複雑なコードブロックの置換にも対応します。default_api.replaceは厳密な文字列一致が必要ですが、replace_regexはより柔軟なパターンマッチングが可能です。

これらのSerenaツールを活用することで、Gemini CLIはあなたのコーディングアシスタントとして、より高度なタスクを自律的に、かつ正確に実行できるようになります。

外部情報検索

Google Web Search (default_api.google_web_search):
Serenaのツールは主にローカルのファイルシステムやコードベースに特化していますが、Gemini CLIにはdefault_api.google_web_searchという強力なウェブ検索ツールが組み込まれています。

このツールは、Serenaがカバーしない広範な情報（最新の技術トレンド、ライブラリのドキュメント、一般的な知識など）をインターネットから取得するために不可欠です。

Serenaによるコードの深い理解と、Google検索による最新の外部情報の組み合わせにより、Gemini CLIはあらゆる開発タスクにおいて、より包括的で正確なアシスタンスを提供できるようになります。

まとめ

Serena MCPをVSCodeとGemini CLIに導入することで、あなたの開発環境はより強力でインテリジェントなものになります。

コードの深い理解、効率的な操作、そしてVSCodeとのシームレスな連携により、開発プロセスが大幅に改善されるでしょう。一度導入して再起動すれば、Gemini CLIは自動的にSerenaの高度なツールを認識し、あなたの指示に応じて最適なツールを自律的に選択・活用するようになります。

コードの深い理解、効率的な操作、そしてVSCodeとのシームレスな連携により、開発プロセスが大幅に改善されるでしょう。

一度導入して再起動すれば、Gemini CLIは自動的にSerenaの高度なツールを認識し、あなたの指示に応じて最適なツールを自律的に選択・活用するようになります。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up