Serena MCPとは — Claude Codeへの接続と使い方

Serena MCPとは

Serena MCPは、AIエージェントにIDEのようなシンボル単位のコード検索・編集・リファクタリングを足すMCPサーバーです。Claude Codeにも接続でき、入れ方はuv tool install -p 3.13 serena-agent、serena init、serena setup claude-codeの3コマンドで、/mcpに表示されれば接続できています。

ファイル全体を読み込む代わりに、関数やクラスの構造と参照関係を直接扱い、Claude CodeやCodex、CursorなどMCP対応クライアントに「IDE相当のコード理解」を足します。

Serena自身はコードを書きません。ツール群を提供する立場で、判断とツール呼び出しはClaude Codeなどのエージェント側が行います。ライセンスは分かれており、シンボル解析を担うsolidlspはMIT、Serena本体はGPL-3.0-or-laterです。

Serena MCPでできること

正規表現検索・ファイル読み込み・シェル実行といった基本機能もありますが、Claude Codeのように同等機能を内蔵するクライアントでは既定で無効です。具体的にどのツールが外れるかは、後述の「--context claude-codeで外れるツール」で示します。正規表現での内容置換に使うreplace_contentは除外されず、編集に使えます。

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

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

単一言語のコード検索とシンボル編集が中心なら、無料のLSPで足ります。移動・インライン化や型階層の参照を多用するなら、JetBrains側が選択肢になります。

Serena MCPは必要か

小さなリポジトリや、数ファイルの文章・設定の編集が中心なら、Claude Code内蔵のGrepとReadで足ります。Serenaが効くのは、大きく複雑なコードベースでの参照元の検索、ファイルをまたぐリネーム、シンボル単位の編集です。

Serenaの公式READMEも、効果が出やすい場面を「大規模で複雑なコードベース」としています。READMEに載るエージェント自身の評価でも、小さなテキスト編集やコード以外の作業は内蔵ツールに任せると書かれています。

入れてから不要だと感じたら、次の節のuv tool uninstall serena-agentで外せます。登録した側はclaude mcp remove serenaで消します。

インストールとClaude Codeへの接続

Serenaはパッケージマネージャーuvで管理されます。uvが未導入なら先に入れてください。

uv tool install -p 3.13 serena-agent
serena init

JetBrainsバックエンドならserena init -b JetBrainsです。バックエンドは初期化後も設定ファイルで切り替えられます。更新はuv tool upgrade serena-agent、削除はuv tool uninstall serena-agentです。

最短の接続は、自動セットアップコマンドです。

serena setup claude-code

手動で入れるなら、登録先のスコープを選びます。Claude Code v2.1.287のclaude mcp add --helpでは、--scopeはlocal・user・projectの3択で、省略時はlocalです。

# 全プロジェクト共通(ユーザースコープ)
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のドキュメントによると~/.claude.jsonにプロジェクトのパス付きで保存されます。.mcp.jsonで共有したいときは--scope projectを付けます。Serenaのドキュメントが「プロジェクト単位」と呼ぶ構成は、Claude Code側の用語ではローカルスコープに当たります。

なおserena initは、Serenaの設定ファイルを初期化してバックエンドを選ぶコマンドです。Claude Codeへの登録はserena setup claude-codeか上のclaude mcp addが担います。

接続後は/mcpでSerenaの状態を確認します。起動が遅くて切断される場合は、export MCP_TIMEOUT=60000のように環境変数を引き上げます。

--context claude-codeで外れるツール

--context claude-codeは、Claude Codeが内蔵する機能と重なるツールを外し、シンボル系だけを残す設定です。同梱のclaude-code.ymlは、次の6ツールを除外しています。

• create_text_file・read_file: ファイルの作成と読み込み
• execute_shell_command: シェル実行
• find_file・list_dir: ファイル名検索とディレクトリ一覧
• search_for_pattern: 正規表現検索

つまりSerena経由の正規表現検索は使えず、パターン検索はClaude Code側のGrepに任せる構成です。同じ設定には、エージェントへの指示文も入っています。探索にRead、編集にEditを使うことを禁じる内容です。代わりにget_symbols_overviewとfind_symbol、replace_symbol_bodyなどを優先させます。Serenaで読んだ内容をClaude Code内蔵のEditで書き換えると、内蔵側が「読んでいない」と見なして拒否します。そのため、編集もSerenaのツール(replace_symbol_bodyやreplace_contentなど)で行うよう促しています。

もう一つの効果が、プロジェクト切り替えツールの無効化です。single_project: trueの設定により、起動時にプロジェクトが渡されていればactivate_projectは使えません。このため、--projectか--project-from-cwdでプロジェクトを渡して起動する構成が前提になります。渡さない場合はactivate_projectが残り、会話の中でアクティブ化する形になります。

CodexでSerena MCPを使うとき

Codexではserena setup codexを実行します。手動なら~/.codex/config.tomlの[mcp_servers.serena]に、command = "serena"とargs = ["start-mcp-server", "--project-from-cwd", "--context=codex"]を書きます。Codexは全体設定の構成なので、Codexアプリでは作業の最初に「Activate the current dir as project using serena」と頼むのが安全です。接続の確認は、Codexでも/mcpでできます。Codex用のフックは~/.codex/hooks.jsonに、Claude Codeとは別の構成で書きます。

プロジェクトの準備とオンボーディング

Serenaの作業は、プロジェクト作成、アクティブ化、オンボーディングの順に進みます。

プロジェクト単位のメモリは.serena/memories/、全プロジェクト共通のグローバルメモリは既定で~/.serena/memories/global/に置かれます。人間が普通のエディタで直せて、プロジェクトのコードと一緒にコミットやレビューもできます。エージェントには起動時にメモリ名の一覧が渡され、必要なものを名前から選んで読みます。参照先がリネームで古くなったかはserena memories checkで調べられます。

大規模なコードベースでは、先にserena project create --indexか、作成後のserena project indexでシンボル情報をキャッシュしておけます。最初のシンボル検索の待ちを避けるための操作で、実行は1回で足り、その後はファイル変更に合わせて自動更新されます。JetBrainsバックエンドではIDE側が索引を持つため不要です。

セッションの様子は、Serenaのダッシュボードで見られます。既定のアドレスはhttp://localhost:24282/dashboard/index.htmlで、ポートが使用中なら大きい番号になります。ツール呼び出しの履歴とログを見られるので、Serenaのツールが実際に呼ばれているかの確認に向きます。設定やメモリをその場で編集したり、サーバーを停止したりする操作もダッシュボードからできます。

Serenaのツールが使われないときの対処

つまずきの代表は、接続できているのにClaude Codeが内蔵のGrepやReadばかり使うことです。公式の説明では、Claude Codeの内蔵ツールの説明文は1万6000トークン近くに達し、ユーザーは調整できません。この説明文が内蔵ツールへの強い偏りを生み、Opus 4.7にSerenaを使わせるのはほぼ不可能だと書かれています。

最初の対処は、起動時にシステムプロンプトを差し替える方法です。

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

Claude Codeの--system-promptは、既定のシステムプロンプト全体を置き換えます。既定の指示を足すだけの--append-system-promptとは動作が違います。同じ内容をCLAUDE.mdに書く手もありますが、Serenaのドキュメントは内蔵ツールへの偏りを打ち消すには足りない場合があると述べています。

次の対処がフックです。.claude/settings.json(プロジェクト単位)か~/.claude/settings.json(全体)に、必要なものだけ追加します。

{
  "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"
          }
        ]
      }
    ]
  }
}

原因はClaude Codeの動的なツール読み込みです。ツールを最初に読み込めなかったり、長いセッションで指示を忘れたりする「エージェントドリフト」が起きるため、リマインドフックで補います。フックは「アルファ機能」の扱いで、問題はGitHubのIssueトラッカーに報告する前提です。フック機構の全体像は、Elicitation/ElicitationResultフックでMCP入力要求を横取りするにあります。

残る症状と対処は次のとおりです。

serenaコマンドが見つからない: PATHに入っていてもクライアントが認識しないことがあります。その場合は実行ファイルのフルパスをMCP起動コマンドに書きます。

一部の言語サーバーが動かない: 環境変数が必要な言語があります(macOSのHomebrew環境のF#など)。MCPサーバーの設定にenvを明示します。

Streamable HTTPで複数プロジェクトを扱いたい: Serenaはステートフルで、1インスタンスが同時に持てるアクティブなプロジェクトは1つです。プロジェクトごとに別のインスタンスをstdioで起動するのが基本の構成です。同じプロジェクトを複数のエージェントで使う場合は、1つのインスタンスをHTTPで共有できます。

セキュリティ上の注意点

Serenaはファイルの書き換えとシェル実行のツールを持ちます。セキュリティモデルは、ローカルマシン、MCPクライアント(LLM)、扱うコードリポジトリ、ユーザー設定、パッケージマネージャーの設定の5つが信頼できる前提です。

ツール単位の制限では意図しない結果を完全には防げず、確実な方法はDockerなどによるサンドボックス化だと明記されています。サンドボックス化しなければ、Serenaが触れる範囲はそのままフル権限です。

v1.6.0からは「信頼済みプロジェクト」があります。ルートパスが設定ファイルのtrusted_project_path_patternsに一致しないプロジェクトでは、次の2つが無効になります。プロジェクトを開いただけで走るシェルコマンド(activation_command)と、言語サーバーの取得元を上書きするls_specific_settingsなどです。v1.6.0より前から使っている設定には全プロジェクトを信頼するパターンが残り、新規作成した設定は既定でどのプロジェクトも信頼しません。

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

まとめ

Serenaを入れるときの分かれ目は、スコープ(全プロジェクトかこのプロジェクトか)と、フックまで設定するかの2つです。接続直後にダッシュボードの呼び出し履歴でmcp__serena__が出ているかを見れば、フックまで要るかを判断できます。

MCPサーバー全般のツール数管理はAIコーディングエージェントのMCP対応状況を比較するにあります。コード実行の設計はMCPでコード実行する設計です。他のMCP導入例はTerraform MCPサーバーの使い方をご覧ください。