Claude Code で Serena MCP を使ってエージェントがセマンティックなコード分析をできるようにする方法です。
Claude Code 1.0.67
Serena 0.1.3
Serenaとは
Serena は、AIコーディングエージェントがコードをセマンティック（意味論的）に解析・編集できるようにするためのツールです。
AIコーディングエージェントは、クラス名やメソッド名を文字列として検索することでコードを探すことが多いです。
これに対してSerenaを使うと、コードの「意味」を理解した上での分析が可能になります。
具体的には以下のような分析が可能になります。
- 特定のクラスを継承している全てのクラスを見つける
- あるメソッドがどのクラスで定義されているかを正確に特定する
- インターフェースの実装関係を追跡する
- 変数やメソッドの参照元を網羅的に検出する
- など
要はより人間ぽくなります（良い意味で）。
.NETでいうところの Roslyn のセマンティック解析と同様の概念です。
Claude Code で Serena を MCP として使用すると、これらのセマンティックな解析機能が利用できるようになります。
さらに、解析したプロジェクトのシンボルや関係性の情報を保存し、次回以降の分析で再利用することで、トークン使用量を大幅にできるという利点もあります。
SerenaをMCPサーバとして起動する環境構築
さてそれでは Serena を MCP サーバとして起動するための環境構築を行います。
方法はいくつかあるのですが、今回は手軽に最新版のSerenaを利用できるuvxコマンドを使った方法を紹介します。
uvはPythonのパッケージ管理ツールです。
まだインストールしていない場合は、以下のコマンドを実行してください。
curl -LsSf <https://astral.sh/uv/install.sh> | sh
インストールが完了したらTerminalを再起動して以下のコマンドでバージョンを確認します。
uv --version
バージョン情報が表示されればインストール完了です。
Claude CodeにSerena MCPサーバの設定を追加
環境が整ったら、Claude CodeにSerena MCPサーバの設定を追加します。プロジェクトのルートディレクトリで以下のコマンドを実行してください：
claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant --project $(pwd)
オプションの意味はざっくり以下のとおりです。詳細は公式READMEを参照してください
この設定が完了したらClaude Codeを起動します。
起動後しばらく待つとブラウザで下図の画面が自動的に開きます。
さらに確認のため、Claude Codeで/mcpコマンドを実行します。Serenaが正常に動作していれば、利用可能なMCPツールの一覧にSerenaのツールが表示されます。
Claude Code v1.0.52以降では、SerenaのMCPツールが自動的に認識されます。それ以前のバージョンでは、/mcp__serena__initial_instructionsコマンドを手動で実行する必要がありました。最新版を使用することで、この手順は不要になっています。
設定が完了すると、プロジェクトのルートにproject.ymlファイルが生成されます。このファイルにはプロジェクトレベルの設定が保存されます。
オンボーディング
では次に「オンボーディング」という、Serenaがプロジェクトの構造を理解し、今後の分析に必要な情報を記憶する処理を実行します。
オンボーディングは実際に処理を依頼した時に必要だったら適宜やってくれるようですが、コンテキストを大量に消費する可能性があるため独立したセッションでやっておいた方が良さそうです。
Claude Codeに「Serena MCP でオンボーディングを行ってください」みたいな感じに指示するとやってくれると思います。
オンボーディングが終了すると以下のように.serena/memories内にプロジェクトの分析結果が保存されます。
ちなみに project.yml は Serena MCP 起動時に作られると思います。このプロジェクトにおけるSerenaの設定が書き込まれます
使い方
オンボーディングが完了したら通常どおりClaude Codeに指示を出すだけでSerenaの機能を使ってくれます。
「Fooメソッドを呼んでいるメソッドとそのクラス名を全部教えて」とか指示してみるとSerenaが使われることを確認できると思います。
確実に使って欲しかったら明示的に「Serenaを使って〜」と指示すると良いかと思います。
