Serena MCPサーバー導入完全ガイド｜コード検索の使い方

Serena MCPサーバー導入完全ガイド｜コード検索の使い方

Serena MCP とは

Serena は oraios/serena が開発する MCP 向けコーディングツールキット で、grep や行番号ベースの編集ではなく シンボル単位の検索・参照・リファクタリング をエージェントに提供します。Language Server Protocol（LSP）または JetBrains プラグイン（有料・トライアルあり） をバックエンドに、IDE に近い意味理解でコードベースを操作する設計です。

公式 README は「MCP や plugin marketplace 経由でインストールしないでください — 古く最適でないコマンドが含まれます」と明記しています。正しい導入は Quick Start の uv tool install です。本記事は Connecting Your MCP Client を軸に、Claude Code 設定、hooks、既知の注意点を整理します。

前提環境

追加の言語サーバー依存（Homebrew の dotnet 等）は言語ごとに必要になる場合があります。MCP 設定の env に DOTNET_ROOT 等を明示する例が Clients ドキュメント にあります。

インストール（marketplace 禁止）

Do not install Serena via an MCP or plugin marketplace!

uv で CLI を入れる

uv tool install -p 3.13 serena-agent

成功後、シェルで serena コマンドが解決します。

初期化

serena init

既定は language server バックエンド です。JetBrains バックエンドを使う場合は -b JetBrains（別ドキュメント参照）。成功メッセージが出れば LSP 連携の前提は整っています。

LSP 40+ 言語とできること

Serena の LSP バックエンドは、シンボル検索・参照検索・rename・replace symbol body 等を提供します（機能の詳細は Tools ドキュメント）。

JetBrains プラグイン側は move、inline、型階層、デバッグ REPL 等、より IDE 寄りの機能が増えますが 有料（無料トライアルあり）です。個人が Claude Code + OSS LSP で始めるのが一般的な入口です。

Claude Code への接続

推奨セットアップコマンド

serena setup claude-code

対話的に Claude Code 用 MCP エントリを整えます。

手動: グローバル（全プロジェクト）

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 サーバーが running か確認します。

system-prompt override（重要）

Serena 公式 Clients - Claude Code は、Claude Code と Opus 系モデルにおいて 組み込みツール説明が長く、Serena ツールが使われにくい 問題を報告しています。対策として system prompt override を強く推奨しています。

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

serena cc-system-prompt-override の内容を CLAUDE.md に追記する方法もありますが、効果が不十分な場合がある と公式は述べています。Serena を本気で使うセッションでは起動コマンドへの組み込みを検討してください。

hooks（Claude Code）

Claude Code の dynamic tool loading 等により、Serena ツールが読み込まれない・セッション中に忘れる（agent drift）事例があるため、公式は reminder hooks を推奨します。.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"
          }
        ]
      }
    ]
  }
}

hooks は alpha 機能 と明記されています。問題があれば GitHub issue へ、と公式は案内しています。

MCP_TIMEOUT

Serena 起動に LSP 初期化時間がかかると、Claude Code がタイムアウトすることがあります。公式推奨:

export MCP_TIMEOUT=60000

シェルプロファイル（.zshrc 等）に追加し、値は環境に応じて調整してください。

クライアント別の mode of operation

General Instructions より:

Claude Code は cwd をプロジェクト根とする --project-from-cwd または $(pwd) が典型です。モノレポでは Serena の project workflow ドキュメントでルートとパッケージの扱いを確認してください。

基本ツールとハーネスとの重複

Serena には read_file、grep、execute_shell_command 等の basic utilities もありますが、Claude Code や Codex 等の agentic harness 内では既定で無効 になることが多く、ハーネス側ツールと重複を避けるためです。Serena の価値は find_symbol / find_referencing_symbols / replace_symbol_body 等のシンボル操作に置くのが公式の想定です。

実践プロンプト例

Serena で UserService クラスの定義位置を見つけ、参照箇所を一覧してからリネーム影響を説明して

activate the current dir as project using serena

（グローバル MCP 設定時の有効化例 — JetBrains Copilot 節 に類似プロンプトあり）

replace_symbol_body で validateEmail 関数だけを Zod バリデーション付きに書き換えて

grep だけに頼るより シンボル名を明示 すると Serena ツール選択率が上がります。

よくあるつまずき

FAQ

Q. marketplace から入れてはいけないのは本当ですか。 GitHub README で 明示的に禁止 されています。Quick Start の uv 経路が唯一の正規入口です。

Q. JetBrains プラグインは必須ですか。 必須ではありません。無料の LSP バックエンド が既定です。JetBrains IDE 内 Copilot 等で深い IDE 連携が必要なら有料プラグインを検討します。

Q. Claude Code 以外でも使えますか。 VS Code、Codex、Claude Desktop、Copilot in JetBrains 等、MCP 対応クライアント向け手順が Clients ドキュメント に分かれています。

Q. hooks は必須ですか。 必須ではありませんが、Claude Code では Serena 利用率向上のため強く推奨 とされています。

Q. Skills と Serena の違いは？ Skills は手順・プロンプト拡張、Serena は コードの意味的操作 MCP ツール です（Skills 入門）。

Q. 40+ 言語すべてで同じ品質ですか。 LSP 実装の成熟度は言語ごとに差があります。公式 Language Support ページで対象言語と追加依存を確認してください。

関連記事

• MCPサーバーとは？AIエージェントに“道具”を持たせる仕組み
• Playwright MCP完全導入ガイド｜セットアップと実践
• Figma MCPリモート版完全ガイド｜デザイン連携から実装
• Claude Code Skills入門｜SKILL.mdの書き方
• Claude Code セットアップ完全ガイド

正本: github.com/oraios/serena / Clients ドキュメント

最終確認日: 2026-07-23