コンテンツにスキップ

Claude Code 完全ガイド

Serena MCP実装ガイド（最新版）— uv/Claude連携の正しい手順

はじめに

結論から：これまでの npm/Node 前提の手順は公式と不整合です。Serena は uv（Python）で走る MCP サーバーをクライアント（Claude Code/Claude Desktop/Cursor）から起動して使うのが正しい導入方法です。設定ファイルは YAML（~/.serena/serena_config.yml と <project>/.serena/project.yml）で自動生成されます。本稿は公式に沿った最短手順と、クライアント別の正しい設定場所、ダッシュボード/SSE、注意点と既知の課題をまとめます。

この記事のポイント

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

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ごとの既定パス）に追記：

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

保存後にアプリを再起動します。

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"]
    }
  }
}

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

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

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

# <project>/.serena/project.yml（プロジェクト設定）
read_only: false   # CIや安全域が狭い環境では 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

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. トラブルシューティング（既知の論点）

  • 接続できない／途中で停止する: Serena の GitHub Issues を参照（接続・安定性の既知事例あり）
  • Cursor の mcp.json パス解決問題（Windows など）: Cursor の Issue 参照
  • まずは read_only: true で開始し、危険なツールを無効化して原因切り分け

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

  • 公式は MCP サーバー主体。Serena を Node ライブラリとしてCIから直接叩く設計は想定外
  • 静的解析は既存の ESLint/flake8/mypy 等と棲み分け、Serena は対話支援・ローカル作業の加速に活用
  • 無料・APIキー不要: Serena 自体は無料だが、実際の LLM 利用条件はクライアント依存（Claude など）

まとめ

  • 導入は uv ベースの MCP サーバーが正。npm 前提は非推奨
  • 設定は YAML（~/.serena/serena_config.yml, <project>/.serena/project.yml）
  • クライアント別に設定場所が異なる点に注意（Claude Code/Desktop/Cursor）
  • まずはクイックスタート → ダッシュボード確認 → インデックス作成 → read_only 運用から開始

関連記事

参考リンク