概要
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 に依存せずフルパスで登録するのが確実