Claude Code + Serena MCPサーバー：セッション連動型管理の実装

はじめに

開発現場でClaude Codeを使用する際、「特定のタスク時のみMCPサーバー（Serena）を使いたい」「Claude Codeを終了したらMCP接続も自動的に切れてほしい」というニーズは非常に一般的です。手動でMCPサーバーを追加・削除する運用では、終了時の削除を忘れがちで、不要な接続が残り続けてしまう問題があります。

本記事では、Claude CodeのセッションライフサイクルにMCPサーバー接続を連動させる実装方法を解説します。具体的には「手動でSerena接続→Claude Code終了時に自動切断」という仕組みを構築し、開発者が意識せずともセッション終了時にクリーンな状態に戻す方法を紹介します。

セッション連動型MCP管理の課題と解決アプローチ

従来の手動管理における問題点

Claude CodeでのMCP管理において、従来の手動アプローチでは以下の課題がありました：

問題1：終了時の削除忘れ

# 作業開始時にSerenaを追加
claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server

# 作業終了時に削除を忘れる
# → 次回Claude Code起動時もSerena接続が残っている

問題2：複数セッション間での状態干渉

• プロジェクトAでSerenaを追加
• プロジェクトBに移動してもSerena接続が残存
• 意図しないプロジェクトでMCPサーバーが動作

問題3：リソース無駄遣い

• 不要なMCPサーバープロセスが長時間稼働
• ネットワーク接続やメモリリソースの継続消費

セッション連動型管理の基本思想

これらの問題を解決するため、以下の原則に基づいたセッション連動型管理を実装します：

1. 手動接続開始：開発者が明示的にMCPサーバーを起動
2. 自動接続終了：Claude Codeセッション終了時に自動的に切断
3. セッション独立性：各Claude Codeセッションは独立したMCP状態を持つ

実装方法1：シェルフック機能の活用

EXITトラップを使った自動削除

最も簡潔なセッション連動型管理は、シェルのEXITトラップを活用する方法です：

#!/bin/bash
# serena-session.sh

# 終了時の自動削除を設定
cleanup_mcp() {
    echo "Claude Codeセッション終了 - MCP接続をクリーンアップ中..."
    claude mcp remove serena 2>/dev/null || true
    echo "Serena接続を削除しました"
}

# EXITトラップを登録
trap cleanup_mcp EXIT

# Serenaを手動で追加
echo "Serena MCPサーバーを起動中..."
claude mcp add serena -- \
  uvx --from git+https://github.com/oraios/serena \
  serena start-mcp-server \
  --context ide-assistant \
  --project "$(pwd)" \
  --mode bugfix \
  --mode no-onboarding

echo "Serenaが有効になりました。Claude Codeを使用してください。"
echo "このターミナルを閉じるかCtrl+Cで終了すると、Serena接続が自動削除されます。"

# Claude Codeを起動（別ターミナルで実行を想定）
echo "別ターミナルで 'claude' コマンドを実行してください。"

# セッション継続（フォアグラウンドで待機）
echo "セッション継続中... (Ctrl+C で終了)"
while true; do
    sleep 1
done

この方法により、スクリプト終了時に自動的にSerena接続が削除されます。

プロセス監視による自動削除

より高度な実装として、Claude Codeプロセスを監視してセッション終了を検出する方法があります：

#!/bin/bash
# claude-session-monitor.sh

SERENA_NAME="serena"

# Serenaを起動
start_serena() {
    echo "Serenaを起動中..."
    claude mcp add "$SERENA_NAME" -- \
      uvx --from git+https://github.com/oraios/serena \
      serena start-mcp-server \
      --context ide-assistant \
      --project "$(pwd)" \
      --mode bugfix
    echo "Serena接続が完了しました"
}

# Serenaを削除
stop_serena() {
    echo "Serenaを削除中..."
    claude mcp remove "$SERENA_NAME" 2>/dev/null || true
    echo "Serena接続を削除しました"
}

# Claude Codeプロセスの監視
monitor_claude_process() {
    while true; do
        # Claude Codeプロセスが動いているかチェック
        if ! pgrep -f "claude" >/dev/null; then
            echo "Claude Codeプロセスが終了しました"
            stop_serena
            exit 0
        fi
        sleep 2
    done
}

# メイン処理
start_serena

echo "Claude Codeを起動してください..."
echo "Claude Code終了時に自動的にSerena接続を削除します"

# バックグラウンドで監視開始
monitor_claude_process &
MONITOR_PID=$!

# Ctrl+C対応
trap "kill $MONITOR_PID 2>/dev/null; stop_serena; exit" INT TERM

# 待機
wait $MONITOR_PID

実装方法2：ラッパースクリプトによる統合管理

Claude Code統合ラッパー

Claude Codeの起動から終了までを一括管理するラッパースクリプトを作成する方法です：

#!/bin/bash
# claude-with-serena.sh

SERENA_NAME="serena-$(date +%s)"  # ユニークな名前生成
PROJECT_DIR="$(pwd)"

# クリーンアップ関数
cleanup() {
    echo "セッション終了 - Serena接続をクリーンアップ中..."
    claude mcp remove "$SERENA_NAME" 2>/dev/null || true
    echo "✓ MCP接続がクリーンアップされました"
    exit 0
}

# シグナルハンドリング
trap cleanup EXIT INT TERM

echo "🚀 Claude Code + Serenaセッションを開始中..."

# Serenaを起動
echo "📡 Serenaを接続中..."
claude mcp add "$SERENA_NAME" -- \
  uvx --from git+https://github.com/oraios/serena \
  serena start-mcp-server \
  --context ide-assistant \
  --project "$PROJECT_DIR" \
  --mode bugfix \
  --mode no-onboarding

if [ $? -eq 0 ]; then
    echo "✓ Serena接続完了 (名前: $SERENA_NAME)"
else
    echo "❌ Serena接続に失敗しました"
    exit 1
fi

echo "📝 プロジェクト: $PROJECT_DIR"
echo "🎯 モード: バグ修正"
echo ""
echo "Claude Codeを起動中..."
echo "終了時は Ctrl+C を押すか、このターミナルを閉じてください"
echo ""

# Claude Codeを起動（同一プロセス内）
claude

# Claude Code終了後、自動的にcleanup()が実行される

使用例

# 実行権限を付与
chmod +x claude-with-serena.sh

# Claude Code + Serenaセッション開始
./claude-with-serena.sh

# → Claude Codeが起動し、Serenaが利用可能
# → Claude Code終了時に自動的にSerena接続も削除される

Serena使用時の実践的なワークフロー

このラッパーを使用した実際の開発フローは以下のようになります：

# 1. プロジェクトディレクトリに移動
cd /path/to/your/project

# 2. セッション開始
./claude-with-serena.sh

# 3. Claude Code内でSerenaを活用
# 例：「現在のスタックトレースを解析して修正箇所を特定してください」
# 例：「この機能のテストケースを生成してください」

# 4. 作業完了後、Ctrl+C または claude 終了
# → 自動的にSerena接続が削除される

# 5. 確認（次回起動時）
claude mcp list
# → 何も表示されない（クリーンな状態）

実装方法3：プロジェクト固有の自動化設定

プロジェクト別セッション管理

プロジェクトごとに異なるMCP設定を自動適用し、セッション終了時に自動削除する方法です：

#!/bin/bash
# project-claude.sh

# プロジェクト設定ファイルの読み込み
if [ -f ".claude-session.conf" ]; then
    source ".claude-session.conf"
else
    echo "プロジェクト設定ファイル (.claude-session.conf) が見つかりません"
    echo "デフォルト設定を使用します"
    SERENA_ENABLED="true"
    SERENA_MODE="bugfix"
fi

# セッションID生成
SESSION_ID="session-$(date +%Y%m%d-%H%M%S)"
SERENA_NAME="serena-$SESSION_ID"

# クリーンアップ関数
cleanup_session() {
    echo ""
    echo "🧹 セッションクリーンアップを開始..."
    
    if [ "$SERENA_ENABLED" = "true" ]; then
        claude mcp remove "$SERENA_NAME" 2>/dev/null && echo "✓ Serena削除完了"
    fi
    
    # 他のMCPサーバーもここで削除可能
    echo "✅ セッション終了処理が完了しました"
}

# シグナルハンドリング
trap cleanup_session EXIT INT TERM

echo "🔧 プロジェクト固有のClaude Codeセッションを開始..."
echo "📁 プロジェクト: $(basename $(pwd))"
echo "🆔 セッション: $SESSION_ID"

# Serena設定
if [ "$SERENA_ENABLED" = "true" ]; then
    echo "🤖 Serenaを起動中 (モード: $SERENA_MODE)..."
    
    claude mcp add "$SERENA_NAME" -- \
      uvx --from git+https://github.com/oraios/serena \
      serena start-mcp-server \
      --context ide-assistant \
      --project "$(pwd)" \
      --mode "$SERENA_MODE" \
      --mode no-onboarding
      
    if [ $? -eq 0 ]; then
        echo "✓ Serena接続完了"
    else
        echo "❌ Serena接続失敗 - 継続します"
    fi
fi

echo ""
echo "🚀 Claude Code起動中..."
claude

# 終了時にcleanup_session()が自動実行

プロジェクト設定ファイル例

# .claude-session.conf
# プロジェクト固有のClaude Code + MCP設定

# Serena設定
SERENA_ENABLED="true"
SERENA_MODE="feature-dev"  # or "bugfix"

# 追加のMCP設定（今後の拡張用）
# CUSTOM_MCP_ENABLED="false"
# PROJECT_API_ENABLED="true"

運用上のベストプラクティス

セッション管理のエイリアス設定

頻繁に使用するセッション管理スクリプトには、エイリアスを設定して効率化を図ります：

# ~/.bashrc または ~/.zshrc への追記
alias claude-serena='~/scripts/claude-with-serena.sh'
alias claude-project='~/scripts/project-claude.sh'
alias claude-clean='claude mcp list | grep -q "serena\|project" && echo "MCP接続を手動削除してください" || echo "✓ MCP接続はクリーンです"'

使用例とワークフロー

# 1. 通常のバグ修正セッション
claude-serena

# 2. プロジェクト固有設定でのセッション
cd /path/to/project
claude-project

# 3. セッション状態の確認
claude-clean

複数開発者環境での標準化

チーム開発では、共通のセッション管理スクリプトをリポジトリに含めることを推奨します：

# プロジェクトルートに配置
project-root/
├── .claude-session.conf      # プロジェクト設定
├── scripts/
│   └── claude-session.sh     # セッション管理スクリプト
└── README.md                 # 使用方法の記載

README.mdでの使用方法記載例：

## Claude Code + Serena使用方法

1. セッション開始
   ```bash
   ./scripts/claude-session.sh

2. 作業完了後、Ctrl+C または Claude Code終了 → 自動的にMCP接続がクリーンアップされます

3. 設定変更は .claude-session.conf で行ってください

## トラブルシューティング

### よくある問題と解決法

<strong>問題1：「スクリプト終了時にMCP接続が残っている」</strong>

原因：`trap`が正常に動作していない、またはシグナルが正しく処理されていない

解決法：
```bash
# デバッグ用にtrapの動作を確認
trap 'echo "EXIT trap executed"; claude mcp remove serena' EXIT

# 強制終了に対応
trap 'echo "Interrupt received"; claude mcp remove serena; exit' INT TERM

問題2：「複数のSerena接続が残る」

原因：ユニークなMCP名生成が機能していない

解決法：セッション開始前にクリーンアップを実行

# セッション開始時のクリーンアップ
cleanup_old_connections() {
    claude mcp list | grep "serena-" | while read name; do
        claude mcp remove "$name" 2>/dev/null || true
    done
}

問題3：「プロセス監視が機能しない」

原因：pgrepの検索条件が広すぎる、または狭すぎる

解決法：より具体的なプロセス検索条件を使用

# 改良版プロセス監視
monitor_claude_process() {
    CLAUDE_PID=$(pgrep -f "claude$" | head -1)
    if [ -n "$CLAUDE_PID" ]; then
        while kill -0 "$CLAUDE_PID" 2>/dev/null; do
            sleep 2
        done
        echo "Claude Codeプロセス($CLAUDE_PID)が終了しました"
        stop_serena
    fi
}

セッション連動管理の効果と利点

従来手法との比較

項目	従来の手動管理	セッション連動管理
接続開始	手動 claude mcp add	手動（スクリプト実行）
接続終了	手動 claude mcp remove	自動（セッション終了時）
削除忘れリスク	❌ 高い	✅ なし
セッション独立性	❌ 状態が干渉	✅ 完全に独立
運用負荷	❌ 高い（毎回削除要）	✅ 低い（自動処理）

実装による効果

開発者体験の向上

• 「Claude Code終了→自動的にクリーン状態」により、次回起動時の状態を気にする必要がない
• プロジェクト切り替え時の設定干渉を完全に防止
• セッション終了忘れによるリソース無駄遣いを解消

チーム開発の効率化

• プロジェクト固有設定により、開発者間での設定統一が容易
• 「スクリプト実行→作業→終了」のシンプルなワークフロー
• セットアップ手順の標準化と自動化

まとめ

Claude Codeにおけるセッション連動型MCP管理により、「手動接続→自動切断」の理想的な運用が実現できます。重要なポイントは：

1. 手動接続開始：開発者が明示的にMCP接続を制御
2. 自動接続終了：Claude Code終了時の確実なクリーンアップ
3. セッション独立性：プロジェクト間での状態干渉防止
4. スクリプト化による標準化：チーム全体での一貫した運用
5. トラブル対応の簡素化：自動処理によるヒューマンエラー削減

この手法により、MCPサーバー（特にSerena）の利点を活用しながら、運用負荷を最小限に抑えた開発環境を構築できます。セッション管理の自動化は、AI支援開発をより実践的で持続可能なものにする重要な要素です。

参考文献

• Model Context Protocol公式ドキュメント
• Anthropic公式 - Model Context Protocol発表
• Serena MCP Server - GitHub Repository
• uv - Python Package Manager公式ドキュメント
• Claude Code公式ドキュメント