Serena MCPの始め方 — 導入とClaude Code/Codex CLI設定・エラー対処【2026年版】
Serena MCPは公式が「旧uvxコマンドは非推奨」と明言済み。最新のserena setupでのClaude Code/Codex CLI/Cursor別設定と接続エラー対処法をまとめた。
エンジニアのゆとです。
Serena MCPを検索すると、QiitaやZennに「導入してみた」記事がたくさん出てくる。ただし2026年9月時点で読むと、そのほとんどが uvx --from git+https://github.com/oraios/serena serena-mcp-server --project-dir という古いコマンドを使っている。
これは今のSerena公式リポジトリのREADMEで名指しで「非推奨」と書かれている手順だ。
Do not install Serena via an MCP or plugin marketplace! They contain outdated and suboptimal installation commands. Instead, follow our Quick Start instructions.
この記事では、公式ドキュメントと実際のGitHub Issueをベースに、2026年9月時点で正しいSerena MCPの入れ方と、Claude Code / Codex CLI / Cursor など主要クライアント別の設定、そしてよくある接続エラーの対処法までまとめた。
Serena MCPとは何か
Serena MCPは、LSP（Language Server Protocol）をAIコーディングエージェントから使えるようにするMCPサーバーだ。オープンソースで、GitHubスターは2万8千を超えている（2026年9月時点）。
LSPはもともと「VS CodeやIntelliJが関数定義へのジャンプや参照検索をするときに内部で使っているプロトコル」だ。Serenaはこれをそのまま流用し、Claude CodeやCodex CLIといったエージェントに「シンボル単位でコードを検索・編集する」能力を渡す。
具体的に何が変わるかというと、たとえば「この関数を呼んでいる箇所を全部探して」という指示に対して、grepベースのエージェントは文字列検索で探す。変数に代入されていたり、継承経由で呼ばれていたりする「動的な参照」は見落としやすい。
Serena MCPが入っていると、LSP経由で「シンボルの参照先」を検索する。IDEの「Find All References」と同じ精度で、型情報まで含めて解析する。大規模なリファクタリングや複雑な依存関係の調査で差が出やすい。
対応言語はPython・TypeScript・Go・Rust・Java・C#・Ruby・PHPなど40以上（公式ドキュメント記載）。JetBrains IDEを持っている場合は、LSPの代わりに有料のSerena JetBrainsプラグインを使う選択肢もある。こちらはリネームやインライン化、デバッガ連携までカバーする分、無料のLSPバックエンドより機能が広い。
公式ドキュメントでは、Claude Code（Opus 4.6）・Codex CLI（GPT 5.4）・Copilot CLI（GPT 5.4）それぞれの環境でSerenaありなしの作業を比較した評価結果が公開されている。エージェント自身の評価コメントとして「クロスファイルのリネームや参照検索が、8〜12ステップかかっていた作業が1回の呼び出しに収束する」といった趣旨の記述がある。数値の実測は公式の評価ページに譲るが、狙っている効果の方向性はここに表れている。
導入前に知っておくべき最重要ポイント：旧来の手順はもう非推奨
冒頭で触れた通り、Serena公式は「MCPマーケットプレイスやプラグイン経由でのインストール」「uvx --from git+... 形式の古いコマンド」を名指しで非推奨としている。
理由は明言されていないが、READMEの構成を見る限り、Serena本体のインストール（uv tool install）とMCPサーバーの起動（serena start-mcp-server）を分離したことが大きい。旧方式は毎回GitHubからソースを取得して起動する形だったため、バージョンの固定がしづらく、起動も遅くなりやすかったと推測できる。
新方式では「Serenaを一度だけツールとしてインストールする」→「クライアントごとに起動コマンドを設定する」という2段階に変わっている。この記事はこの新方式で統一して書く。
もし既存のプロジェクトで古い uvx --from git+... 形式の設定をすでに使っている場合、動作は今のところ止まっていないはずだが、公式が非推奨と明言している以上、次に設定を触るタイミングで新方式に移行しておいた方がいい。
事前準備 — uvのインストール
Serenaは uv（Python製のパッケージマネージャ）で管理されている。これが唯一の必須の前提条件だ。
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows（PowerShell）
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"インストール後、以下でバージョンが表示されればOKだ。
uv --versionSerena本体のインストールと初期化
uvが入ったら、Serena本体をツールとしてインストールする。
uv tool install -p 3.13 serena-agent成功すると、シェルから serena コマンドが使えるようになる。続けて初期化コマンドを実行する。
serena initこれでSerenaが正しくセットアップされたかを検証できる。デフォルトではLSPバックエンドが使われる設定になる。JetBrainsプラグインを使いたい場合は serena init -b JetBrains を指定する。
初期化に成功すると成功メッセージが表示される。ここまでで「Serenaが動く状態」は整った。次はクライアント（Claude Code・Codex CLIなど）側に接続設定を追加する。
クライアント別セットアップ手順
Serenaはクライアントごとに --context オプションで動作モードを切り替える設計になっている。同じ serena start-mcp-server コマンドでも、渡す --context の値でシステムプロンプトや利用可能なツールが変わる。
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)"--project-from-cwd は「Claude Codeを起動したディレクトリを自動的にプロジェクトとして扱う」オプションだ。複数プロジェクトを行き来する場合はこちらの方が手間が少ない。
公式ドキュメントには注意書きがある。最近のClaude CodeとOpus系モデルのアップデートで、Serenaのツールを使うよう指示しても従わないケースが増えたという趣旨の記述だ。回避策として、システムプロンプトを上書きして起動する方法が案内されている。
claude --system-prompt="$(serena prompts print-cc-system-prompt-override)"Serenaのツールをエージェントに使わせたいのに使ってくれない、という場合はまずこれを試すといい。
Codex CLI
こちらも自動セットアップコマンドがある。
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 CLI内で /mcp を実行し、Serenaが接続済みと表示されれば成功だ。
Windows環境では後述するPATH関連のエラーが出やすいので、うまく繋がらない場合はトラブルシューティングの章を先に見てほしい。
Cursor / Gemini CLI / Cline など
公式ドキュメントはCursorとGemini CLIについて専用の手順書を用意していない。ただしこれらは「MCP対応のIDE・ターミナルクライアント」として一括りにされていて、共通の起動パターンが推奨されている。
serena start-mcp-server --context ideCursorであればMCP設定ファイル（~/.cursor/mcp.json またはプロジェクトの .cursor/mcp.json）に、Gemini CLIであれば対応するMCP設定ファイルに、上記コマンドを起動コマンドとして登録する形になる。設定ファイルのフォーマットはクライアントによって微妙に違うので、各クライアントの「カスタムMCPサーバーの追加方法」のドキュメントと合わせて設定する。
{
"mcpServers": {
"serena": {
"command": "serena",
"args": ["start-mcp-server", "--context", "ide", "--project", "${workspaceFolder}"]
}
}
}${workspaceFolder} のような変数展開に対応していないクライアントの場合は、プロジェクトの絶対パスを直接書く。
VS Code + GitHub Copilot
VS Codeの場合、グローバル設定とワークスペース設定で起動コマンドが変わる。
# グローバル
serena start-mcp-server --context=vscode
# ワークスペース単位
serena start-mcp-server --context=vscode --project ${workspaceFolder}VS Codeのコマンドパレットから「MCP: Add Server」を実行し、Command（stdio）を選んで上記コマンドを入力する流れになる。
公式ドキュメントには既知のバグとして「グローバルモードだとVS Code側の不具合でプロジェクトが自動アクティベートされない」という記載がある。この場合、セッション開始時にチャットで「Activate the current dir as project using serena」のように明示的に指示する必要がある。
プロジェクトのインデックス化
大きめのプロジェクトでは、初回起動前にインデックスを作っておくと初回起動が安定する。
serena project indexプロジェクトのルートディレクトリで実行する。LSPが各ファイルのシンボル情報を解析してキャッシュを作る処理で、プロジェクトの規模によっては数十秒〜数分かかる。
このインデックス作成を省略していきなりクライアントから接続すると、後述する「初回接続時にタイムアウトする」問題が起きやすい。特にファイル数の多いプロジェクトでは、先にインデックスを作っておくことを勧める。
よくあるトラブルと対処法
ここからは実際にSerenaのGitHub Issueで報告されている症状をベースに、対処法を整理する。
接続エラー・タイムアウトで繋がらない
Claude CodeやCodex CLIで「Serena MCP server failed to connect」のようなエラーが出るケースが複数報告されている。
Issueのやり取りを追うと、多くは「プロジェクトを初めて開いたとき、Serenaがgitignoreの解析や言語検出をバックグラウンドで行うため、起動直後の応答が遅れる」ことが原因とみられている。2回目以降の起動では発生しなくなった、という報告が多い。
対処法は主に2つ。
1つ目は、事前に serena project index でインデックスを作っておく（上の章の内容）。
2つ目は、クライアント側のMCP接続タイムアウトを伸ばす。
export MCP_TIMEOUT=60000Claude Codeの場合、この環境変数をシェルの起動ファイル（.zshrc や .bashrc）に設定してから起動し直すと解消するケースが多い。
どうしても解決しない場合、SSEモード（Serenaサーバーを自分で起動してURL経由で接続する方式）に切り替えるとタイムアウトの問題自体を回避できる、という選択肢も公式に案内されている。
Windows・Codex CLIでPATH関連のエラーが出る
WindowsのCodex CLI環境で、Serenaが起動できない・ダッシュボードにアクセスできないという報告がある。原因は「Codex CLIがMCPサーバーのプロセスに環境変数（PATHなど）をうまく引き継がない」ことだった。
~/.codex/config.toml に環境変数を明示的に追加することで解決している。
[mcp_servers.serena.env]
SystemRoot = "C:\\Windows"
WINDIR = "C:\\Windows"
PATH = "C:\\Users\\ユーザー名\\AppData\\Roaming\\uv\\bin;C:\\Windows\\System32;C:\\Windows"
[mcp_servers.serena]
command = "serena"
args = ["start-mcp-server", "--project-from-cwd", "--context=codex"]PATHの中身は自分の環境の uv インストール先に合わせて書き換える必要がある。WSL2環境であれば、Windows側のパス問題自体が発生しないため、Codex CLIをどうしても使いたい場合はWSL2経由の方が設定が単純になる。
Claude Codeで claude mcp add が「already exists」で失敗する
同じ名前（serena）のMCPサーバーがすでに登録されている状態で claude mcp add serena ... を実行すると、重複エラーになる。設定をやり直したいときによくハマる。
一度削除してから追加し直せば解決する。
claude mcp remove serena
claude mcp add --scope user serena -- serena start-mcp-server --context claude-code --project-from-cwdclaude mcp list で現在登録されているMCPサーバーの一覧と、どのスコープ（ユーザー / プロジェクト）に登録されているかを確認できる。プロジェクトスコープとユーザースコープの両方に同名で登録してしまっているケースもあるので、迷ったら一覧で確認してから消すのが早い。
Serenaのツールをエージェントが使ってくれない
接続自体は成功しているのに、Claude Codeがずっとgrepやreadを使い続けてSerenaのシンボル検索ツールを呼ばない、という相談も見かける。
前述したシステムプロンプト上書き（serena prompts print-cc-system-prompt-override）が一つの対処法だが、それとは別に公式はSessionStart / PreToolUseのフックを設定してエージェントに定期的にリマインドする仕組み（serena-hooks）も用意している。ただしこの機能はまだアルファ扱いで、クライアントによって挙動の調整が必要になる。
まずはプロンプト上書きを試して、それでも改善しない場合にフック設定を検討する、という順番がシンプルだ。
実際に何が変わるのか
Serenaを入れると、grepやfindに頼っていた「文字列ベースの検索」が「シンボルベースの検索」に置き換わる。
具体的な体感としてよく語られるのは、大規模なリファクタリング作業だ。ある関数の名前を変える、インターフェースのシグネチャを変える、といった変更をエージェントにやらせるとき、Serenaなしだと「その関数名を含むファイルを全部grepして、1つずつ確認しながら書き換える」という手順を踏みがちだ。動的に呼ばれている箇所や、別名でimportされている箇所は見落とされることがある。
Serenaがあると「このシンボルを参照している箇所」をLSP経由で正確に列挙できるため、見落としが減る。公式の評価ページでは、この種の作業が「複数ステップの手探り」から「1回のツール呼び出し」に集約される、という方向性のフィードバックが複数のモデル・クライアントの組み合わせで一致して得られたとされている。
一方で、小さいスクリプトや1ファイル完結の作業では、LSPの解析コストの方が上回ることもある。プロジェクトの規模や作業内容によって効果の出方が変わる点は踏まえておいた方がいい。
向いている人・向いていない人
向いている人は、複数ファイルにまたがる中〜大規模なコードベースを日常的に触っていて、リファクタリングや依存関係の調査をエージェントに任せたい人だ。TypeScript・Python・Go・Javaあたりの主要言語であればLSPの成熟度も高く、恩恵を受けやすい。
向いていない人は、単一ファイルの小さいスクリプトが中心の作業、あるいはLSPが対応していない独自言語・DSLを使っている場合だ。この場合はSerenaのセットアップコストに見合うリターンが出にくい。
複数のAIコーディングツール（Claude Code・Codex CLI・Cursorなど）を併用している場合は、Serenaを一度インストールしておけば --context を変えるだけで全部のクライアントから使い回せる。ツールを掛け持ちしている人ほど導入の価値は上がる。
セキュリティ・注意点
SerenaはLSP経由でプロジェクト全体のコード構造を解析する。基本的にはローカルで完結する処理で、外部にコードを送信するわけではないが、エージェント自身（Claude CodeやCodex CLIなど）が解析結果をモデルに渡す点は変わらない。機密性の高いコードベースで使う場合、そもそもエージェント自体の利用ポリシーに準拠しているかを確認しておく必要がある。
また .serena フォルダにはプロジェクトの設定・メモリファイル・キャッシュが保存される。gitignoreに追加しておかないと、意図せずリポジトリにコミットしてしまうことがあるので注意したい。
echo ".serena/" >> .gitignoreFAQ
Q: Serena MCPは無料？
コア機能（LSPバックエンド）はオープンソースで無料。JetBrainsプラグインを使う場合は有料（無料トライアルあり）。
Q: どの言語で一番効果が出る？
公式が挙げている40以上の対応言語の中でも、TypeScript・Python・Go・Java・C#あたりはLSP実装が成熟していて安定して動く。逆に対応言語表に載っていない独自言語やDSLでは使えない。
Q: Claude Code・Codex CLI・Cursorを同時に使っていても大丈夫？
問題ない。Serena本体は一度インストールすれば、クライアントごとに --context オプションを変えて起動するだけで済む。プロジェクトのインデックスも共有される。
Q: 旧方式（uvx --from git+...）ですでに設定している場合、今すぐ移行すべき？
今のところ動作自体が止まっているわけではない。ただし公式が明確に非推奨としている以上、設定を触るタイミングで新方式（uv tool install → serena setup）に移行しておいた方が、将来のアップデートで急に動かなくなるリスクを避けられる。
まとめ
Serena MCPは「LSPでシンボルベースの検索・編集ができるようになる」という価値自体は変わっていないが、2026年に入って公式のインストール方法が大きく変わった。ネット上の解説記事の多くがまだ旧方式のままなので、これから導入する場合は必ず公式リポジトリのQuick Startを確認してから進めた方がいい。
流れを整理すると以下の通りだ。
uv tool install -p 3.13 serena-agentでSerena本体をインストールserena initで初期化を確認- クライアントごとに
serena setup <クライアント名>か、--contextを指定した手動設定を追加 - 大きいプロジェクトは
serena project indexを先に実行 - 繋がらない場合はまずタイムアウト（
MCP_TIMEOUT）を疑う
他のMCPサーバーもあわせて整理したい場合はこちらも参考にしてほしい。
