Claude Codeに入れておきたいMCP、Serenaについてと、個人的にハマったところ

この記事はLLM(Claude Sonnet 4)による補助によって作成されています

最近、Claude CodeにSerena MCPを導入しました。実際に使ってみると、普通に便利だったので、Serena MCPの概要から、個人的にハマったところを共有します。

この記事でわかること

• Serena MCPとは何か、どのような仕組みで動作するのか
• LSP（Language Server Protocol）を活用したセマンティック解析の威力
• 実際の導入手順と使用時の注意点・よくあるトラブル
• 大規模コードベースでの実用性と効果的な活用方法

この記事の対象者

• Claude Codeを日常的に使用している開発者の方
• 大規模なプロジェクトでのコード解析に課題を感じている方
• MCPツールの活用に興味がある方
• LSPやセマンティック解析の実用性を知りたい方

動作環境・前提条件

動作環境

• OS: macOS Sequoia（Windows、Linuxでも動作可能）
• ツール: Claude Code
• Python: 3.8以上（Serena MCPのインストールに必要）
• uvもインストールしておいてください

前提条件

• Claude Codeがインストール済み
• 分析対象のプロジェクトが存在する

Serena MCPとは何か？

Serena MCPは、Claude CodeにLSP（Language Server Protocol）ベースのコード解析機能を追加するMCPサーバーです。

従来のClaude Codeは、ファイルを個別に読み込んで分析する形でしたが、Serena MCPを導入することで：

• 関数やクラスの定義・参照関係の把握
• プロジェクト全体の構造情報の取得
• シンボル検索とセマンティック分析
• 効率的なファイル間の関連性理解

これらが可能になります。

どのような仕組みで動作するのか？

LSP（Language Server Protocol）による構造理解

VSCodeなどのエディタで、F12キーを押すと「定義に移動」できますよね。これは以下のような情報をエディタが解析しているからです：

• この関数はどこで定義されている？
• この関数を参照している場所は？
• このクラスにはどのようなメソッドがある？

Serena MCPはこのLSPプロトコルを活用し、関数やクラスの定義・参照関係・プロジェクト全体の構造情報を取得します。

セマンティック解析によるコード理解

単なるテキスト検索ではなく、関数、クラス、依存関係などの意味的な繋がりをLSPの情報を元に解析します。これにより、コードベース全体を意味的に関連するもので瞬時に特定できるようになります。

ローカル完結・高い信頼性

• 大規模・複雑なリポジトリでも問題なく解析可能
• 他人の書いたコードもセマンティック分析で効率的に理解可能
• すべてローカル環境で完結するため、セキュリティ面でも安心

利用可能なツール一覧

Serena MCPを導入すると、Claude Codeで以下の豊富なツールが使用可能になります：

ファイル操作ツール

基本的なファイル操作機能を提供します。

• mcp__serena__read_file - ファイルの内容を読み取り（指定した行範囲も可能）
• mcp__serena__create_text_file - 新しいファイルの作成、または既存ファイルの上書き
• mcp__serena__list_dir - ディレクトリ内のファイルとディレクトリの一覧表示
• mcp__serena__find_file - ファイルマスクを使用したファイル検索

正規表現・行編集ツール

精密なコード編集を支援します。

• mcp__serena__replace_regex - 正規表現を使用した内容の置換
• mcp__serena__delete_lines - 指定した行の削除
• mcp__serena__replace_lines - 指定した行範囲の置換
• mcp__serena__insert_at_line - 指定した行への内容挿入

検索・パターンマッチングツール

コードベース全体での効率的な検索機能です。

• mcp__serena__search_for_pattern - コードベース内での任意のパターン検索

シンボル関連ツール（最重要）

LSPを活用した最も強力な機能群です。

• mcp__serena__get_symbols_overview - ファイルまたはディレクトリのシンボル概要取得
• mcp__serena__find_symbol - 名前パスによるシンボル検索
• mcp__serena__find_referencing_symbols - 指定シンボルを参照するシンボルの検索
• mcp__serena__replace_symbol_body - シンボルの本体置換
• mcp__serena__insert_after_symbol - シンボルの後への内容挿入
• mcp__serena__insert_before_symbol - シンボルの前への内容挿入

メモリ管理ツール

プロジェクトの知識を蓄積・管理します。

• mcp__serena__write_memory - プロジェクトに関する情報をメモリに保存
• mcp__serena__read_memory - メモリファイルの内容読み取り
• mcp__serena__list_memories - 利用可能なメモリの一覧表示
• mcp__serena__delete_memory - メモリファイルの削除

システム・プロジェクト管理ツール

プロジェクト全体の管理機能を提供します。

• mcp__serena__execute_shell_command - シェルコマンドの実行
• mcp__serena__activate_project - プロジェクトのアクティベート
• mcp__serena__remove_project - プロジェクトの削除
• mcp__serena__switch_modes - 動作モードの切り替え
• mcp__serena__get_current_config - 現在の設定情報の表示

オンボーディング・状態管理ツール

プロジェクトの初期設定と状態確認機能です。

• mcp__serena__check_onboarding_performed - オンボーディング実行状況の確認
• mcp__serena__onboarding - オンボーディングプロセスの開始

思考・分析ツール

AI支援による高度な分析機能です。

• mcp__serena__think_about_collected_information - 収集した情報の分析
• mcp__serena__think_about_task_adherence - タスクの進捗状況確認
• mcp__serena__think_about_whether_you_are_done - 作業完了状況の確認
• mcp__serena__summarize_changes - 実行した変更の要約

その他のツール

システム管理とセッション管理機能です。

• mcp__serena__restart_language_server - 言語サーバーの再起動
• mcp__serena__prepare_for_new_conversation - 新しい会話の準備

導入手順と初期設定

1. プロジェクトのアクティベート

Serena MCPを使用する際は、プロジェクトのアクティベートが必須です。

Claude Codeのチャット欄で以下のコマンドを実行：

/mcp__serena__initial_instructions

または、チャットで「プロジェクトのアクティベートをして」と指示します。

これにより：

• .serenaディレクトリが作成される
• オンボーディング（プロジェクトの全体像把握と初回分析）が実行される
• メモリーファイルが自動生成される

2. インデックス作成（大規模プロジェクト向け）

大きなプロジェクトの場合、事前にインデックスを作成することで分析速度が向上します：

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

.serenaディレクトリを削除しても自動で復活するため、インデックスは自動更新されます。

使用時の注意点とよくあるトラブル

アクティベートを忘れがち

最もよくある問題は、プロジェクトをアクティベートせずに使用しようとすることです。

アクティベートされていないと「先にアクティベートしろ」というエラーが表示され、Claude Codeは通常のbashコマンドで解析しようとしてしまいがちです。

セキュリティ面での注意

Serena MCPはシェルコマンド実行機能も持っているため、allow toolに指定するとリスキーな場合があります。
実行するコマンドを個別に許可する設定ができるかどうかは、要検証

メモリーファイルの管理

オンボーディング時に複数のメモリーファイルが作成されますが、内容が重複している場合があるそうです。定期的に人間が監視・整理することをお勧めします。

実際の効果と使用感

大規模プロジェクトでの威力

従来のClaude Codeでは、数百ファイル規模のプロジェクトを扱う際に：

• ファイル構造の把握に時間がかかる
• 関数の定義場所を特定するのに複数回のやり取りが必要
• 依存関係の理解が困難

Serena MCP導入後：

• プロジェクト構造を瞬時に把握
• 関数・クラスの定義から参照まで一発で特定
• 関連ファイルの自動発見

具体的な改善例

Before（従来のClaude Code）：

「この関数がどこで使われているか調べて」
→ ファイルを一つずつ検索
→ 複数回のやり取りが必要
→ 見落としの可能性

After（Serena MCP導入後）：

「この関数がどこで使われているか調べて」
→ find_referencing_symbols で一発検索
→ 全参照箇所を即座に特定
→ コードスニペット付きで表示

エージェント機能について

Serena MCPにはAIエージェント機能も搭載されていますが、個人的には：

• セマンティック解析
• 関連ファイルの検索
• シンボル解析

これらの基本機能だけでも十分すぎるほど有用だと感じています。

まとめ

Serena MCPの導入により、Claude Codeのコード理解能力は劇的に向上しました。

✅ 優れている点

• LSPベースの正確なコード解析 - 意味的な関連性を正確に把握
• 大規模プロジェクト対応 - 数百ファイル規模でも問題なく動作
• ローカル完結 - セキュリティ面で安心
• シンボル検索の威力 - 定義・参照・依存関係を瞬時に特定

⚠️ 注意点

• 初期設定が必要 - プロジェクトのアクティベートを忘れずに
• セキュリティ考慮 - シェルコマンド実行機能の取り扱いに注意
• メモリー管理 - 自動生成されるメモリーファイルの定期的な整理

大規模なコードベースでClaude Codeを活用したい開発者にとって、Serena MCPは必須ツールと言えるでしょう。従来の「ファイルを読み込んで分析」という手法から、「プロジェクト全体をセマンティックに理解」する次元へと、確実にステップアップできます。

おまけ

LSP活用しないツール（パターン検索や、read_fileなど）は、マークダウンファイルでも検索できました。
Obsidianなど、マークダウンファイルがたくさんある場合でも、活用ができそうです。