Serena MCPでClaude Codeのコード理解をシンボル単位に強化する

Serena MCPとは

Serena MCPは、コードをシンボル単位で検索・編集・リファクタリングできるオープンソースのMCPサーバーです。ファイル全体を読み込む代わりに、関数やクラスといったシンボルの構造・参照関係を直接扱い、Claude CodeやCodex、CursorなどMCP対応クライアントに「IDE相当のコード理解」を追加します。

Serena自身はコードを書きません。あくまでツール群を提供する立場で、実際の判断とツール呼び出しはClaude Codeなどのエージェント側が行います。ライセンスはコンポーネントによって分かれており、シンボル解析を担うsolidlsp部分はMITライセンス、それ以外のSerenaアプリケーション本体はGPL-3.0-or-laterです。

Serena MCPでできること

Serena MCPの機能は、シンボル検索(Retrieval)・リファクタリング・シンボル単位編集・メモリ管理の4つに大別されます。

シンボル検索は、ファイルを開かずにシンボル単位でコードを探索する機能です。find_symbol(シンボル検索)、ファイル単位のシンボル一覧取得、あるシンボルを参照している箇所の検索(find referencing symbols)、診断情報の取得などが含まれます。

リファクタリングは、言語サーバーバックエンドではシンボルのリネームのみに対応し、シンボル・ファイル・ディレクトリの移動やインライン化、未使用コードの伝播削除は有料のJetBrainsプラグインバックエンド限定です。

シンボル単位編集は、シンボル本体の置き換え(replace symbol body)、シンボルの前後への挿入、安全な削除(safe delete)を指し、こちらは言語サーバー・JetBrainsプラグインの両バックエンドで使えます。

メモリ管理は、プロジェクトの規約や設計判断をセッションをまたいで記憶する機能です。メモリ同士はmem:名前という記法で相互参照でき、リネーム時も参照が追従します。

これらに加えて、正規表現検索・ファイル読み込み・シェルコマンド実行といった基本機能も持ちますが、Claude CodeやCodexのようにエージェント自身が同等の機能を内蔵しているハーネスでは、これらの基本機能は既定で無効化されます。

バックエンドの使い分け早見表

Serenaは「言語サーバー(LSP)バックエンド」と「JetBrainsプラグインバックエンド」の2種類から選べます。無料で使えるLSPバックエンドが既定です。

複数言語のリファクタリングや型階層の参照を頻繁に使うなら、JetBrainsプラグインバックエンドの導入を検討する価値があります。単一言語のコード検索・シンボル編集が中心であれば、無料のLSPバックエンドで要件を満たせます。

インストール手順

Serenaはパッケージマネージャーuvで管理されています。uvが未導入の場合は先にインストールしてください。

uv tool install -p 3.13 serena-agent

インストール後、ターミナルでserenaコマンドが使えるようになります。続けて初期化コマンドを実行し、動作を確認します。

serena init

JetBrainsプラグインバックエンドを使う場合はserena init -b JetBrainsを実行します。バックエンドは初期化後も設定ファイルからいつでも切り替え可能です。

アップデートとアンインストールは次のコマンドで行います。

uv tool upgrade serena-agent
uv tool uninstall serena-agent

Claude Codeへの接続方法

Claude CodeへのSerena MCP追加は、公式が用意する自動セットアップコマンドが最短です。

serena setup claude-code

手動で設定する場合は、用途に応じて2通りのコマンドがあります。すべてのプロジェクトで使いたいならユーザースコープ、特定のプロジェクトだけなら現在のディレクトリを指定するプロジェクトスコープです。

全プロジェクト共通で使う場合(--project-from-cwdは起動ディレクトリから自動でプロジェクトを検出します)。

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が内蔵しているファイル操作・シェル実行と重複する基本機能を無効化し、シンボル検索・編集系のツールだけを提供する設定です。

接続後は/mcpコマンドでSerenaが接続されているか確認します。起動が遅くタイムアウトする場合は、シェルの設定ファイルにexport MCP_TIMEOUT=60000のように環境変数を追加し、タイムアウトの閾値を引き上げます。

プロジェクトのアクティブ化とオンボーディング

Serenaはプロジェクト単位で動作します。ワークフローは、プロジェクト作成 → アクティブ化 → オンボーディング → コーディング作業、という4段階です。

--project引数を指定して起動した場合(前節のClaude Code向けコマンドはどちらもこの形です)、そのプロジェクトは起動時に自動でアクティブ化されます。claude-codeのような単一プロジェクト向けコンテキストでは、起動時にプロジェクトが渡されていれば、プロジェクトを切り替えるactivate_projectツール自体が無効化されます。これは1つのプロジェクトだけを扱う想定のもとでの設計です。

プロジェクトを明示的に作成し、大規模なコードベースであらかじめシンボル情報をキャッシュしておきたい場合は、次のコマンドを使います。

serena project create --index

初回起動時には「オンボーディングプロセス」が自動的に走り、プロジェクトの規約や設計判断をメモリとして記録します。このメモリは以降のセッションで再利用され、同じ説明を毎回繰り返す必要がなくなります。

フックで運用を安定させる

ドキュメントは、Claude Codeの内蔵ツールの説明文が最大で約1万6000トークンに達し、これがモデルに内蔵ツールへの強いバイアスをかけることで、Serenaのツールが使われにくくなる問題があると明記しています。回避策として、Claude Code起動時にシステムプロンプトを上書きするコマンドが提供されています。

claude --system-prompt="$(serena prompts print-cc-system-prompt-override)"

さらに安定させるため、.claude/settings.json(プロジェクト単位)または~/.claude/settings.json(全体)にフックを追加することが推奨されています。主なフックは4種類です。

• remind(PreToolUse): grepやread_fileの呼び出しが連続したとき、Serenaのシンボルツールを使うよう促す
• auto-approve(PreToolUse、mcp__serena__*にマッチ): acceptEditsやautoのような許可の緩いモード実行時、Serenaのツール呼び出しを自動承認する
• activate(SessionStart): セッション開始時にプロジェクトのアクティブ化とSerenaの利用方法の読み込みを促す
• cleanup(SessionEnd): セッション終了時にフック用のセッションデータを片付ける

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "serena-hooks remind --client=claude-code" }]
      },
      {
        "matcher": "mcp__serena__*",
        "hooks": [{ "type": "command", "command": "serena-hooks auto-approve --client=claude-code" }]
      }
    ],
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "serena-hooks activate --client=claude-code" }]
      }
    ],
    "SessionEnd": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "serena-hooks cleanup --client=claude-code" }]
      }
    ]
  }
}

ドキュメントはこれらのフックを「アルファ機能」と明記しており、問題が出たときはGitHubのIssueトラッカーへのフィードバックを求めています。Claude Codeのフック機構全体については、Elicitation/ElicitationResultフックでMCP入力要求を横取りするでも扱っています。

セキュリティ上の注意点

Serenaはファイルの書き換えとシェルコマンド実行のツールを持ちます。これはコーディングエージェント向けMCPサーバーとしては本質的な機能であり、セキュリティモデルは「ローカルマシン」「MCPクライアント(LLM)」「扱うコードリポジトリ」「ユーザー設定」「パッケージマネージャーの設定」の5つがいずれも信頼できることを前提にしています。

ドキュメントは、ツール自体の実行制限では意図しない結果を完全には防げず、確実に防ぐ唯一の方法はDockerなどによるサンドボックス化だと明言しています。裏を返せば、サンドボックス化しない限り、Serenaが操作できる範囲はそのままフルの権限になります。

v1.6.0からは「信頼済みプロジェクト」という仕組みが入りました。プロジェクトのルートパスが設定ファイルのtrusted_project_path_patternsに一致しない限り、プロジェクトを開いただけで実行されるシェルコマンド(activation_command)や、言語サーバーの取得元を上書きする設定(ls_specific_settings)などの一部機能が無効化されます。

ネットワーク面では、MCPサーバー自体・ダッシュボード・JetBrainsプラグインサーバーはいずれも既定でlocalhostからの接続のみを受け付けます。言語サーバーの自動取得については、バージョン固定・SHA256ハッシュ検証・ダウンロード元ホストの許可リストという複数の防御策が組まれており、いずれか1つでも一致しなければインストールを中止する設計です。

よくあるつまずき

serenaコマンドが見つからない: PATHに入っているはずなのにクライアントが認識しない場合は、serena実行ファイルのフルパスをMCP起動コマンドに直接指定します。

Serenaのツールが使われない: クライアント側のツール検出処理が原因で、ツールが登録されていてもモデルが呼び出さないことがあります。前節のフック(特にremind)を設定することで改善が見込めます。

起動が遅くタイムアウトする: MCP_TIMEOUT環境変数を引き上げます。大規模なコードベースでは、事前にserena project indexでシンボル情報をキャッシュしておくと、初回ツール呼び出し時の遅延を避けられます。

Streamable HTTPモードでの複数プロジェクト同時利用: Serenaはステートフルなサーバーで、1インスタンスにつき同時にアクティブにできるプロジェクトは1つです。複数のプロジェクトを並行して扱いたい場合は、プロジェクトごとに別々のSerenaインスタンスをstdioモードで起動する構成が推奨されています。

まとめ

Serena MCPは、grepやファイル全読みに頼らずシンボル単位でコードを検索・編集できるMCPサーバーです。Claude Codeへの接続はclaude mcp addコマンド1行、またはserena setup claude-codeの自動セットアップで完了します。無料のLSPバックエンドで大半の用途はカバーでき、複雑なリファクタリングや型階層の参照が必要になった段階で有料のJetBrainsプラグインバックエンドを検討するとよいでしょう。導入後は内蔵ツールへのバイアスでSerenaが使われにくくなる問題があるため、remindフックの設定まで済ませておくと安定して動きます。MCPサーバー全般のツール数管理やコード実行の仕組みは、AIコーディングエージェントのMCP対応状況を比較するやMCPでコード実行する設計、他のMCPサーバー導入例はTerraform MCPサーバーの使い方も参考にしてください。