Serena MCP Server

Serena MCP Server とは？

Serena MCP は Oraios が開発するオープンソースのコーディングエージェント用ツールキットで、AI エージェントに IDE のようなセマンティックなコード検索・編集・リファクタリング・デバッグ機能を提供します。行番号や単純なテキスト検索ではなく、シンボル単位で動作します。

Serena は Claude Code、Codex、Cursor、VS Code、Claude Desktop など、あらゆる MCP クライアントに接続できます。解析機能は 2 つのバックエンドのいずれかで提供されます。無料・オープンソースの言語サーバー（LSP、デフォルト、40 以上の言語に対応）か、JetBrains IDE 自体のコード解析を使う有料の Serena JetBrains Plugin（無料トライアルあり）です。プロジェクトは自らを「コーディングエージェントのための IDE」と位置づけており、大規模で複雑なコードベースほど効果が大きくなります。

Serena MCP Server の使い方

前提条件は uv だけです。メンテナーは MCP やプラグインのマーケットプレイス経由でのインストールを推奨していません。そこに載っているインストールコマンドは古く、最適ではないためです。シェルでインストールして初期化します。

uv tool install -p 3.13 serena-agent
serena init

serena init はデフォルトで言語サーバーバックエンドを設定します。JetBrains プラグインのバックエンドを使う場合は -b JetBrains を付けます。言語によっては追加の言語サーバー依存関係が必要です（ドキュメントの Language Support ページを参照）。

Claude Code

最も手早いのは 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)"

/mcp を実行して接続を確認します。Serena の起動が遅い場合は MCP_TIMEOUT を引き上げてください（例：export MCP_TIMEOUT=60000）。ドキュメントには、長いセッション中にエージェントへ Serena のツールを使うよう促す、オプションの serena-hooks コマンドも用意されています。

Claude Desktop

File / Settings / Developer / MCP Servers / Edit Config を開き、次を追加します。

{
  "mcpServers": {
    "serena": {
      "command": "serena",
      "args": ["start-mcp-server", "--context=desktop-app"]
    }
  }
}

File / Exit で Claude Desktop を完全に終了してから再起動します。

VS Code

MCP: Add Server を実行し、Command (stdio) を選んで serena start-mcp-server --context=vscode（グローバル）または serena start-mcp-server --context=vscode --project ${workspaceFolder}（ワークスペース）を入力します。

Cursor

ドキュメントに Cursor 専用のページはありません。Cursor、Windsurf、Cline、Roo Code などの MCP 対応 IDE では、ツールの重複を減らすために serena start-mcp-server の起動コマンドに --context ide を付けて追加することが推奨されています。

Codex

serena setup codex を実行するか、~/.codex/config.toml に次を追加します。

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

Serena MCP Server の主な機能

• シンボル単位の検索：シンボル、ファイルのアウトライン、参照元のシンボル、宣言、実装を検索。
• シンボル単位の編集：シンボル本体の置換、シンボルの前後への挿入、安全な削除。
• リファクタリング：言語サーバーでシンボル名を変更。移動、インライン化、未使用コードの削除には JetBrains プラグインが必要。
• 対話型デバッグ（JetBrains プラグインのみ）：永続的な REPL でブレークポイント設定、変数の確認、式の評価。
• 無料の LSP バックエンドで Python、TypeScript、Java、Go、Rust、C/C++、C# など 40 以上の言語に対応。
• 長期的なエージェントワークフロー向けのメモリ機能。AGENTS.md などのファイルと併用でき、無効にもできる。
• 階層型の YAML 設定（グローバル、CLI、プロジェクト、コンテキスト、モード）で有効なツールやプロンプトを選択。
• Serena v2 ではオプションの REPL インターフェースが追加され、エージェントが Python で Serena の API を呼び出し、複数の操作を 1 回の呼び出しにまとめられる。

Serena MCP Server のツール

どの構成でも有効になるのはツールの一部だけで、主に Serena の起動時に指定する --context で決まります。

• シンボルツール：ナビゲーション用の find_symbol、get_symbols_overview、find_referencing_symbols、find_declaration、find_implementations。編集用の replace_symbol_body、insert_after_symbol、insert_before_symbol、rename_symbol、safe_delete_symbol。get_diagnostics_for_file はシンボルごとに診断結果を返します。
• JetBrains ツール（オプション）：jet_brains_move、jet_brains_inline_symbol、jet_brains_type_hierarchy、jet_brains_run_inspections、jet_brains_debug。
• ファイル・シェルツール：read_file、list_dir、find_file、search_for_pattern、replace_content、execute_shell_command。同様のツールを備えた Claude Code などの環境では通常無効です。
• メモリツール：write_memory、read_memory、list_memories、edit_memory、delete_memory。
• ワークフロー・設定ツール：activate_project、onboarding、initial_instructions、get_current_config。

Serena MCP Server のユースケース

• シンボル単位で大規模コードベースを探索：「parse_config の呼び出し元をすべて探し、それぞれのエラー処理を要約して。」
• 何度も検索・置換する代わりに、ファイルをまたぐ名前変更を 1 回のアトミックな操作で行う。
• 関数を 1 つだけ書き換える：「UserService.create の本体を、まずメールアドレスを検証するように置き換えて。」
• 多言語のモノレポで参照検索を使って依存関係をたどる。
• JetBrains プラグインでデバッグ：エージェントがブレークポイントを設定し、ステップ実行して変数を確認する。
• Serena のメモリでセッション間のプロジェクトメモを残す。新しいリポジトリでは "Activate the current dir as project using serena." から始める。

Serena MCP Server と代替ツールの比較

Serena の強みは、シンボルを理解したセマンティックなコード作業です。汎用の Filesystem MCP Server はファイルの読み書きしかできず、Context7 や DeepWiki のようなドキュメント系サーバーはライブラリのドキュメントを提供するもので、コードは編集しません。Serena 内では、無料の LSP バックエンドがナビゲーション、シンボル編集、名前変更をカバーし、有料の JetBrains プラグインが移動、インライン化、型階層、デバッグを追加します。

Serena MCP Server のトラブルシューティング

• クライアントが serena コマンドを見つけられない：MCP 設定に serena 実行ファイルのフルパスを指定します。
• ツールは読み込まれるがエージェントが使わない：Claude Code や VS Code 向けの serena-hooks リマインダーフックを設定するか、"Activate the current project with Serena and read initial instructions" と指示します。
• Claude Code での起動タイムアウト：MCP_TIMEOUT を 60000 などに引き上げます。
• 言語サーバーに環境変数が必要：Claude Desktop などの GUI クライアントはシェルのプロファイルを引き継がないことがあるため、serena のサーバー設定に env ブロックを追加します。
• グローバル設定で別のプロジェクトが使われる：Codex、Claude Desktop、グローバルな VS Code 設定では、セッションの最初に現在のディレクトリをプロジェクトとして有効化するようエージェントに依頼します。