コンテンツにスキップ

Claude Code 完全ガイド

Serena MCP設定ガイド: Claude Code・Codex・JetBrains対応（2026年版）

2026年2月更新

  • v1.0.0リリース準備中（v0.1.4が最後のプレリリース）
  • Codex CLI正式対応 --context codexオプション
  • JetBrainsプラグインリリース
  • 30+言語サポート
  • 破壊的変更: replace_regexツールがide-assistant/codexコンテキストから削除

はじめに

結論から：これまでの npm/Node 前提の手順は公式と不整合です。SerenaはMCPサーバとしてuv（Python）経由で起動し、クライアント（Claude Code／Claude Desktop／Cursor）が起動・接続するのが正統ルート。設定ファイルは YAML（~/.serena/serena_config.yml と <project>/.serena/project.yml）で自動生成されます。本稿は公式に沿った最短手順、クライアント別の正しい設定場所、ログとデバッグ、ダッシュボード/SSE、安全策と既知の課題を2025年10月時点の最新情報でまとめます。

この記事のポイント

  • 完全な開発環境構築: Claude と Serena の連携を最短で有効化
  • 実プロジェクト適用: 大規模PJでの初回レスポンス高速化（インデックス）
  • セキュア運用: read_only や任意コマンド実行の制御

Serena MCPサーバークイックチェックリスト（2025年11月版）

Serena MCP server quick checklist

  1. uv経由でサーバーを起動できるか — uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant --project "$(pwd)" を実行し、ダッシュボード http://localhost:24282/dashboard/index.html が開けるか確認。
  2. クライアント設定を三者でそろえる — Claude Codeは claude mcp add、Claude Desktopは %APPDATA%/Claude/claude_desktop_config.json、Cursorは .cursor/mcp.json または設定UIから serena を登録。
  3. YAML設定で安全策を有効化 — ~/.serena/serena_config.yml と <project>/.serena/project.yml の read_only: true を基準に、必要なツールだけ段階的に開放。

表記ゆれ（Serena MCP server / Serena MCPサーバー）で検索しても上記キーワードにヒットするよう、見出しと本文にフレーズを織り込みました。初めての導入時はこの3点を済ませてから詳細セクションを読み進めてください。

1. 最短手順（まずは接続確認）

1.1 Claude Code への追加（推奨）

# プロジェクトルートで実行
claude mcp add serena -- \
  uvx --from git+https://github.com/oraios/serena \
  serena start-mcp-server --context ide-assistant --project "$(pwd)"

1.2 （任意）初回の高速化：プロジェクトインデックス

uvx --from git+https://github.com/oraios/serena serena project index

1.3 動作確認

  • ダッシュボード: http://localhost:24282/dashboard/index.html
  • Claude 側で /mcp__serena__initial_instructions が取得できるか確認（古い版では手動参照が必要）

2. クライアント別セットアップ

2.1 Claude Code（プロジェクト単位・推奨）

claude mcp add serena -- \
  uvx --from git+https://github.com/oraios/serena \
  serena start-mcp-server --context ide-assistant --project "$(pwd)"

必要に応じて uvx ... serena project index で初回レスポンスを高速化。

2.2 Claude Desktop（JSON直編集）

claude_desktop_config.json を編集（OS別パス）：

  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "desktop-app"]
    }
  }
}

保存後にアプリを完全再起動します。ログは同ディレクトリのmcp.logやmcp-server-*.logで確認できます。MCPアイコン（ハンマーマーク）で接続状態を確認してください。

2.3 Cursor（プロジェクト単位）

.cursor/mcp.json を作成（または編集）：

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "ide-assistant"]
    }
  }
}

注意: Windowsではプロジェクト単位のmcp.jsonが効かない事例が報告されています。その場合はCursorの設定UIから登録するとより安定します。

2.4 Codex CLI（OpenAI）

2026年新対応

Serena MCPがCodex CLIを--context codexオプションで正式サポート。

~/.codex/config.toml を編集：

[mcp_servers.serena]
command = "uvx"
args = ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "codex"]

注意: CodexはMCPサーバーに対して「failed」表示することがありますが、ツールは正常動作します（Codex側の既知バグ）。

2.5 JetBrains IDE（Junie / AI Assistant）

2026年新対応

JetBrainsプラグインがリリース — IDEの強力なコード解析機能を活用。

JetBrains IDE設定からMCPを設定。--context ideがJetBrains連携に推奨されます。

3. 設定ファイル（YAMLが正）

Serena は初回起動時に YAML 設定を自動生成します。

# ~/.serena/serena_config.yml（ユーザー設定）
record_tool_usage_stats: true
included_optional_tools: []

# <project>/.serena/project.yml（プロジェクト設定）
read_only: true    # まずはtrueで開始し、必要なツールだけ段階的に開放
project_name: my_project

安全策: execute_shell_command は任意コマンド実行を許す強力なツールです。まずは read_only: true で開始し、必要な機能を理解してから段階的に書込み系ツールを有効化してください。

4. ダッシュボードとSSE

  • ダッシュボード: http://localhost:24282/dashboard/index.html（既定で有効）
  • SSE接続（必要時のみ）:
uv run serena start-mcp-server --transport sse --port 9121

注意: Dockerは実験的でポートやGUIの挙動が異なることがあります。基本的には直接uv経由での起動を推奨します。

5. よくある誤解と修正スニペット

  • 誤: npm install @oraios/serena / node ./node_modules/@oraios/serena/dist/index.js 正: uvx --from git+https://github.com/oraios/serena serena start-mcp-server

  • 誤: 任意場所の mcp-config.json 正: クライアント依存（Claude Desktop: claude_desktop_config.json、Cursor: .cursor/mcp.json、Claude Code: claude mcp add ...）

  • 誤: .serenarc.json（JSON形式） 正: ~/.serena/serena_config.yml と <project>/.serena/project.yml（YAML、自動生成）

6. トラブルシューティング（既知の論点）

Claude Desktopがサーバを認識しない場合

  1. アプリを完全再起動（タスクトレイからも終了）
  2. JSON構文をチェック（カンマ・括弧の過不足）
  3. パスを絶対指定（Windowsの%APPDATA%展開問題はenvで明示指定可能）
  4. 手動起動テスト: uvx --from git+https://github.com/oraios/serena serena start-mcp-server
  5. ログを確認: mcp.log / mcp-server-*.log でエラー詳細を確認
  6. MCP Inspector（公式デバッグツール）でサーバ疎通テスト

Cursorでmcp.jsonが効かない（Windows）

Windowsではプロジェクト単位の.cursor/mcp.jsonが適用されない報告があります。その場合はCursor設定UI（Settings > Features > Model Context Protocol）から登録してください。

Serenaのツールが「failed」表示

Codex等一部クライアントでの表示バグがあり、実際の処理は成功しているケースがあります。ダッシュボードやログで実行結果を確認してください。

一般的なデバッグ手順

  • まずは read_only: true で開始し、危険なツールを無効化して原因切り分け
  • Serena の GitHub Issues で接続・安定性の既知事例を確認

7. CI/運用の考え方（現実的な線引き）

  • MCPはクライアント起動→サーバ自動起動のモデルが正統。Serena を Node ライブラリとしてCIから直接叩く設計は非推奨（静的解析はESLint/flake8等に分離）
  • Serenaは対話支援・ローカル作業の加速に活用。CI/CDの静的解析は既存ツールと棲み分け
  • 無料・APIキー不要: Serena自体は無料のツールキットですが、実際のLLM利用条件はクライアント依存（Claude等のライセンス条件を確認）
  • まずはread_only: trueで開始し、必要最小のツールのみ段階的に有効化

まとめ

  • 導入は uvベースのMCPサーバが正統。npm/Node前提は非推奨
  • 設定は YAML（~/.serena/serena_config.yml, <project>/.serena/project.yml）で自動生成
  • クライアント別に設定場所が異なる：
  • Claude Code: claude mcp add（CLI推奨）
  • Claude Desktop: claude_desktop_config.json（OS別パス）
  • Cursor: .cursor/mcp.json（Windows不具合注意、UI推奨）
  • 安全第一: read_only: true → ダッシュボード確認 → インデックス作成 → 段階的にツール有効化
  • デバッグ: ログ（mcp.log等）、MCP Inspector、GitHub Issuesを活用

関連記事

参考リンク

  1. Serena v0.1.4（2025-08-15公開）は Codex CLI向けの新コンテキスト、Swift/Bash対応、CLI拡張などを含むメンテナンスリリースで、旧タグを参照していたユーザー向けにBreaking changeを解消しています。 ↩