概要

Claude Code で Serena MCP サーバーが接続できなくなった
原因としては廃止されたコマンドで起動していた

事象

Claude Code を起動しても Serena の MCP ツール（mcp__serena__*）が一切読み込まれない
/mcp ダイアログで確認すると、Serena のステータスが ✗ Failed to connect となっている
他の MCP サーバー（Atlassian、Slack 等）は正常に接続されている

原因

3つの問題が重なっていた。

1. 古いコマンド名が登録されていた

Claude Code の local スコープ（プロジェクト固有・個人設定）に、既に廃止されたコマンドで Serena が登録されていた。

# 旧（壊れている）
uvx --from git+https://github.com/oraios/serena serena-mcp-server --context ide-assistant

# 新（正しい）
serena start-mcp-server --context claude-code --project-from-cwd

変更点:

serena-mcp-server → serena start-mcp-server（サブコマンド形式に変更）
--context ide-assistant → --context claude-code（コンテキスト名の変更）
--project /path → --project-from-cwd（カレントディレクトリから自動検出）

2. スコープの優先順位による罠

Claude Code の MCP 設定には3つのスコープがある。

スコープ	説明	優先度
local	プロジェクト固有・個人設定（`.claude.json` 内）	高
project	プロジェクト共有設定（`.mcp.json`）	中
user	全プロジェクト共通（`~/.claude.json`）	低

user スコープに新しい設定を登録しても、local スコープの古い設定が優先されるため、修正が反映されなかった。

3. PATH の問題

uv tool install でインストールした serena コマンドは ~/.local/bin/ に配置されるが、Claude Code がサブプロセスを起動する際の環境にこのパスが含まれていなかった。

# NG: PATHが通っていないため見つからない
"command": "serena"

# OK: フルパス指定
"command": "/Users/<user>/.local/bin/serena"

解決手順

Step 1: Serena を最新のインストール方法で再インストール

# 旧: uvx --from "git+https://github.com/oraios/serena" で毎回リモートから取得
# 新: uv tool としてローカルにインストール
uv tool install -p 3.13 serena-agent@latest --prerelease=allow

注意: PyPI のパッケージ名は serena-agent（serena ではない）。

Step 2: 古い MCP 設定をすべて削除

# local スコープの古い設定を削除（これが最も重要）
claude mcp remove serena -s local

# user スコープも念のため削除
claude mcp remove serena -s user

# project スコープ（.mcp.json）も削除
claude mcp remove serena -s project

ポイント: claude mcp remove serena をスコープ指定なしで実行すると、複数スコープに存在する場合はエラーになり、どのスコープに残っているか教えてくれる。

Step 3: 正しい設定で再登録

# 公式セットアップコマンド（PATHが通っている場合）
serena setup claude-code

# PATHが通っていない場合はフルパスで手動登録
claude mcp add --scope user serena -- /Users/<user>/.local/bin/serena start-mcp-server --context=claude-code --project-from-cwd

Step 4: Claude Code を再起動して確認

claude mcp list
# serena: /Users/<user>/.local/bin/serena start-mcp-server ... - ✓ Connected

調査の過程で役に立ったコマンド

# MCP サーバーの接続状態を一覧表示
claude mcp list

# Serena を手動起動してエラーを確認
uvx --from "git+https://github.com/oraios/serena" serena start-mcp-server --context claude-code

# Serena のログを確認（起動試行の有無がわかる）
ls -lt ~/.serena/logs/$(date +%Y-%m-%d)/

# .claude.json 内の serena 設定を検索
grep -n -C3 "serena" ~/.claude.json

# スコープ指定なしで削除を試みると、存在するスコープが判明する
claude mcp remove serena

教訓

claude mcp list が唯一の真実: .mcp.json を直接編集しても、local スコープの設定が優先されることがある。必ず claude mcp list で実際に使われている設定を確認する
ログが出ない＝起動すらしていない: Serena のログディレクトリに新しいファイルが生成されない場合、コマンド自体が実行されていないことを示す
フルパス指定が安全: MCP サーバーのコマンドは、PATH に依存せずフルパスで登録するのが確実