Claude Code 完全ガイド

Serena MCP設定ガイド: Claude Code・Codex・JetBrains対応（2026年版）

対象 / ポイント

対象: 大きなコードベースで、Claude CodeやCodexへシンボル検索・参照追跡・安全なリファクタリング能力を追加したい開発者

ポイント:

• Serenaは単独のAIではなく、MCP経由でIDE相当のセマンティック操作を追加するOSSツールキット
• 現行の導入経路はuv tool install -p 3.13 serena-agentとserena init
• Claude CodeとCodexは専用のserena setupを使い、/mcpとプロジェクト有効化で接続を検証する

Serenaが追加するもの

Serenaは、言語サーバーまたはJetBrainsプラグインを使ってコードのシンボル構造を理解し、MCPクライアントへ検索・編集・リファクタリング用ツールを提供する¹。

標準のテキスト検索が「文字列がどこにあるか」を探すのに対し、Serenaは次のような問いを扱う。

• このクラスや関数はどこで定義されているか
• どのシンボルがこの関数を参照しているか
• 関数本体だけを置き換えられるか
• シンボル名を参照先まで含めて変更できるか
• 別プロジェクトや依存関係の定義へ移動できるか

小さな1ファイル修正では組み込みの検索と編集の方が速い場合もある。Serenaの価値が出やすいのは、モノレポ、参照関係の多い変更、シンボル単位の探索、複数言語のコードベースだ。

現在の前提

旧記事で使われていたuvx --from git+https://...は現行の推奨導入ではない。Serenaはv1系としてPyPI配布され、公式Quick Startはuv toolを使う²。

2026年7月16日時点の最新リリースはv1.6.0だ。READMEはLSPバックエンドで40を超える言語を列挙し、Python、TypeScript、Java、Go、Rust、C/C++、Swift、Kotlin、Dart、JSON、YAMLなどを扱う³¹。

言語によって追加の言語サーバーやランタイムが必要になる。対応一覧に名前があっても、すべての操作が同じ精度で使えるとは限らない。

1. uvとSerenaを入れる

uvを導入済みか確認する。

uv --version

未導入ならAstral公式手順でuvを入れ、その後Serenaをインストールする。

uv tool install -p 3.13 serena-agent
serena --version
serena init

serena initは既定でLSPバックエンドを初期化し、導入状態を検査する。JetBrainsバックエンドを使う場合は、有料プラグインの導入後に次を使う²。

serena init -b JetBrains

更新はuv tool経由で行う。

uv tool upgrade serena-agent
serena --version

MCPやプラグインのマーケットプレイスに古い起動コマンドが残る場合がある。公式READMEは、マーケットプレイス経由ではなくQuick Startに従うよう明記している¹。

2. Claude Codeへ接続する

最短はSerenaのセットアップコマンドだ。

serena setup claude-code

手動でユーザー全体へ登録する場合は、作業ディレクトリからプロジェクトを決める。

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を再起動し、/mcpでserenaがconnectedになっていることを確認する。続けて次のように依頼する。

Serenaで現在のプロジェクトを有効化し、initial instructionsを読んで。
このリポジトリの主要シンボルを変更せずに一覧化して。

公式ドキュメントは、最近のClaude Codeと一部モデルが組み込みツールを優先し、Serenaツールを使わない場合があると案内している。必要な場合だけ公式のsystem prompt overrideやSerena hooksを検討する。hooksはalpha扱いのため、まず通常設定で再現を確認する⁴。

3. Codex CLI / Appへ接続する

専用セットアップを実行する。

serena setup codex

手動設定では~/.codex/config.tomlへ次を追加する⁴。

[mcp_servers.serena]
startup_timeout_sec = 15
command = "serena"
args = ["start-mcp-server", "--project-from-cwd", "--context=codex"]

Codexを再起動し、/mcpで接続を確認する。Codex Appはセッションが対象リポジトリのディレクトリから始まらない場合があるため、最初に次を依頼する。

Serenaで現在のディレクトリをプロジェクトとして有効化し、initial instructionsを読んで。

4. JetBrainsへ接続する

JetBrainsでは2通りある。

• 無料のLSPバックエンドをMCP経由でCopilot、Junie、AI Assistantへ接続する
• 有料のSerena JetBrains Pluginをバックエンドとして使い、IDEの解析・リファクタリング・デバッグ機能を利用する

GitHub Copilot in JetBrainsのMCP設定例は次の通りだ⁴。

{
  "servers": {
    "serena": {
      "type": "stdio",
      "command": "serena",
      "args": [
        "start-mcp-server",
        "--context=jb-copilot-plugin"
      ]
    }
  }
}

JunieやJetBrains AI Assistantは推奨contextが異なる。クライアント設定ページから、利用する製品の現行例をそのまま選ぶ。複数の場所へ同じMCPサーバーを二重登録しない。

5. プロジェクトを有効化して確認する

接続成功と、目的のコード解析成功は別だ。次の順で検査する。

1. MCPクライアントでSerenaがconnectedになっている
2. 現在のリポジトリをactivateできる
3. get_symbols_overview相当でファイルのシンボル一覧を取得できる
4. find_symbol相当で既知の関数を検索できる
5. find_referencing_symbols相当で参照元を取得できる
6. 変更前にGit statusを確認し、読み取りだけの検査で差分が出ていない

最初からrenameやreplaceを試す必要はない。読み取り操作で言語サーバーとプロジェクト認識を確認し、使い捨てブランチで編集を検証する。

6. 使い分ける

作業	Serena	組み込みツール
シンボルと参照関係の探索	第一候補	補助
関数・クラス単位の置換	第一候補	小変更なら可
複数ファイルのrename	対応言語なら第一候補	文字列置換は注意
READMEや設定ファイルの短い修正	過剰になりやすい	第一候補
ログや任意テキストの正規表現検索	場合による	rgなどが速い

Serenaのbasic toolsはClaude CodeやCodexの組み込み機能と重複するため、推奨contextでは一部が無効になる。ツール数を最大化するより、重複を減らした方が選択ミスとコンテキスト消費を抑えられる。

トラブルシューティング

serenaが見つからない

対話シェルでは見つかっても、GUIクライアントが同じPATHを継承しないことがある。

which serena
uv tool dir --bin

MCP設定のcommandへserenaの絶対パスを入れて再起動する。

MCPは接続するがツールを使わない

• 利用クライアントに合う--contextか確認する
• プロジェクトをactivateし、initial instructionsを読むよう明示する
• 組み込みツールとの重複を減らす
• Claude Codeでは公式ドキュメントのoverride/hooksを、再現を確認してから試す

シンボル解析が失敗する

• 対象言語の追加要件を公式Language Supportで確認する
• リポジトリの依存関係を先にインストールする
• Serenaのログとダッシュボードで言語サーバーの起動失敗を確認する
• モノレポでは対象プロジェクトとworkspace foldersを確認する

セキュリティと運用

Serenaはコードを読み、編集し、構成次第ではシェルも実行できる。MCP登録は信頼できる公式配布だけを使い、次を守る。

• 初回は読み取り中心の権限で試す
• 変更はGit管理された作業ツリーで行う
• 自動承認hooksを使う前に、許可される破壊的ツールを確認する
• 外部公開するHTTP/SSEサーバーには認証とネットワーク境界を設ける
• リポジトリ内のプロジェクト設定もレビュー対象にする

まとめ

現在のSerena導入は、GitHubのmainをuvxで直接起動する旧手順ではない。

uv tool install -p 3.13 serena-agent
serena init
serena setup claude-code   # または serena setup codex

接続後は、プロジェクト有効化、シンボル一覧、既知シンボル、参照元の順で読み取り検証する。Serenaをすべての編集へ使うのではなく、セマンティック情報が価値を持つ変更へ絞ると効果を判断しやすい。

関連記事

• Claude Code完全ガイド
• Claude Code MCP連携ガイド
• Codex CLI総合ガイド

---

1. oraios/serena README ↩↩↩

2. Serena Quick Start ↩↩

3. Serena v1.6.0 release ↩

4. Connecting Your MCP Client — Serena Documentation ↩↩↩