Serena（MCP）実践ガイド：uv/uvx導入から常駐運用・Claude/Gemini連携まで

以下は実際に試し、動作確認した記事です。

Serena × ChatGPT Gemini 連携：対応してない.ps1を読み解かせる裏ワザ公開！

Serenaを使ってChatGPTやClaude、Geminiと連携する実践ガイド。非対応の .ps1 や .bat を読み込ませる設定方法から、エラーの乗り越え方、実際の出力例までを丁寧に紹介。UVによるインストールからプロジェクト構成の裏技まで、リアルな検証をベースに解説します。

minokamo.tokyo

そして、自分でみても読みにくいと感じた次第です。以前の記事はlinuxとwindowsなのかが明確ではないなど不備がありました。実際に確認しながら書いたので読みずらくなりました。そこで読みやすいように整理したもが下記の記事となります。

1. Serenaとは？

Serenaは、自然言語（普段の話し言葉）での指示を、ターミナルで実行可能なコマンドに変換してくれるツールです。

一言でいうと、「あなたのPC環境やプロジェクトの状況を理解した、専用のAIアシスタントサーバー」をローカルに立てるようなものです。

これにより、ClaudeやGPTといったAIエージェントと連携する際に、毎回コードをコピー＆ペーストしたり、プロジェクトの背景を説明したりする手間が不要になります。AIはSerenaを通じてあなたのローカル環境にあるファイルやコードを直接理解し、より文脈に沿った的確なサポートを提供できるようになります。

2. Serenaを導入する利点

Serenaを導入することで、開発やターミナル操作がより速く、安全、そして直感的になります。

3. インストールと実行方法

前提条件

• Python: 3.11（※3.12は実験的サポート、3.13は未対応の可能性あり）
• uv: 高速なPythonパッケージ管理ツール
• Git: ソースコードをダウンロードするために使用

手順

ステップ1: uv のインストール

まだ uv をインストールしていない場合、以下のコマンドを実行します。

Linux/WSL (Ubuntu)の場合:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows（ネイティブ）の場合:

winget install --id astral-sh.uv

ステップ2: Serenaの実行（uvx を使う方法が最も簡単です）

uvx を使うと、リポジトリのクローンや仮想環境の構築を自動で行い、Serenaを直接起動できます。

uvx --from git+https://github.com/oraios/serena serena start-mcp-server

注意: コマンドが変更されています

• 旧: serena-mcp-server
• 新: serena start-mcp-server

✅ PATH問題の解決

現象のまとめ

• uv / uvx は ~/.local/bin/ (Linux/WSL) または %USERPROFILE%\.cargo\bin (Windows) にインストール済み
• でも uvx をシェルで呼び出すと「コマンドが無い」と言われる
• 原因：そのディレクトリが「パス」に入っていない

🔧 解決方法：PATH を一時的に反映（すぐ動かす）

Linux/WSLの場合、以下をそのままコピペして実行:

export PATH="$HOME/.local/bin:$PATH"

その後、再び：

uvx --from git+https://github.com/oraios/serena serena start-mcp-server

💡 これで uvx が認識されるはずです。

🔁 恒久的な解決（次回ログイン時にも使えるように）

bashの場合：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

zshの場合：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

✅ 最後に確認：

which uvx

出力例：

/home/mamu/.local/bin/uvx

Codex CLIとSerenaの恒久連携について

uvx --from ... serena start-mcp-server を一度実行しても、それは一時的なサーバー起動で、次回のログイン時には消えます。

正解レシピ（Codex CLI / TOML・最新版トラッキング）

~/.codex/config.toml（または <project>/.codex/config.toml。プロジェクト側が優先）

# ~/.codex/config.toml

# --- プロジェクトの信頼設定 ---
[projects."/home/mamu/serial"]
trust_level = "trusted"

[projects."/home/mamu/rev"]
trust_level = "trusted"

[projects."/home/mamu/codex-cli"]
trust_level = "trusted"

[projects."/home/mamu/wpbk"]
trust_level = "trusted"

# ----- MCP サーバー定義（Serena） -----
[mcp_servers.serena]
command = "uvx"
args = [
  "--from", "git+https://github.com/oraios/serena",
  "serena", "start-mcp-server",
  "--context", "codex",
  "--enable-web-dashboard=false"
]

バージョン固定したいときだけ git+...@v0.1.4 のようにタグを付ける。

プロジェクト固定で走らせたいときは、末尾に
"--project", "/home/mamu/your-project-abs-path"（絶対パス）を追加。

検証フロー

1. codex をプロジェクトルートで起動 → 入力欄に /mcp
2. 期待される表示内容：

/mcp

🔌 MCP Tools

• Server: serena 
• Command: uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context codex --enable-web-dashboard=false 
• Tools: activate_project, check_onboarding_performed, delete_memory, find_file, find_referencing_symbols, find_symbol, get_symbols_overview, insert_after_symbol, insert_before_symbol, list_dir, list_memories, onboarding, read_memory, replace_symbol_body, search_for_pattern, think_about_collected_information, think_about_task_adherence, think_about_whether_you_are_done, write_memory

🎯 ワンライナー全部貼りたい場合

export PATH="$HOME/.local/bin:$PATH"
uvx --from git+https://github.com/oraios/serena serena start-mcp-server

しかし、現状のままでは：

🔴 uvx --from ... で起動したSerenaはフォアグラウンドで動いている

つまり、ターミナルを閉じるとSerenaも止まる状態です。

✅ バックグラウンド常駐させる方法

以下のいずれかを使えば、Serenaをバックグラウンドで起動できます。

🚀 方法1：nohup + & を使う（手軽）

特徴

• 最も簡単: 1行コマンドですぐ実行
• ログ出力: 出力をファイルに保存
• ターミナル独立: ターミナルを閉じても継続実行

実行方法

# Serenaをバックグラウンドで起動
nohup uvx --from git+https://github.com/oraios/serena serena start-mcp-server > ~/serena.log 2>&1 &

動作確認とログ監視

# プロセス確認
ps aux | grep serena

# ログをリアルタイム監視
tail -f ~/serena.log

# ログ全体を確認
cat ~/serena.log

プロセス終了方法

# プロセスIDを確認
ps aux | grep serena

# プロセス終了（PIDを置き換えてください）
kill [PID]

# または強制終了
pkill -f serena

🖥️ 方法2：tmux で常駐させる（便利）

特徴

• セッション管理: いつでも接続・切断可能
• デバッグ向け: リアルタイムでログを確認
• 柔軟性: 必要に応じてコマンド実行可能

tmuxのインストール（Ubuntu/WSL）

sudo apt update
sudo apt install tmux

tmuxセッションの作成と実行

# 新しいtmuxセッション「serena」を作成
tmux new -s serena

# セッション内でSerenaを起動
uvx --from git+https://github.com/oraios/serena serena start-mcp-server

📌 重要：セッションのデタッチ（切り離し）

Serenaが起動したら、以下のキー操作でセッションから抜けます：

1. Ctrl + b を押す
2. すぐに d を押す

結果: ターミナルに戻りますが、Serenaはtmuxの中でバックグラウンド実行中

セッション管理コマンド

# セッション一覧を確認
tmux list-sessions

# セッションに再接続
tmux attach -t serena

# セッションを削除（Serenaも終了）
tmux kill-session -t serena

⚙️ 方法3：systemd ユニットで自動起動（本格運用）

特徴

• 完全自動化: システム起動時に自動開始
• 障害復旧: 異常終了時の自動再起動
• ログ管理: journalctlでログ一元管理
• 本格運用: サーバー環境での推奨方法

systemdサービスファイルの作成

# サービスファイルを作成
sudo nano /etc/systemd/system/serena.service

サービスファイルの内容

[Unit]
Description=Serena MCP Server
After=network.target
Wants=network.target

[Service]
Type=simple
User=your_username
Group=your_username
WorkingDirectory=/home/your_username
Environment=PATH=/home/your_username/.local/bin:/usr/local/bin:/usr/bin:/bin
ExecStart=/home/your_username/.local/bin/uvx --from git+https://github.com/oraios/serena serena start-mcp-server
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

サービスの有効化と管理

# systemdにファイルを再読み込み
sudo systemctl daemon-reload

# サービスを有効化（自動起動設定）
sudo systemctl enable serena.service

# サービス開始
sudo systemctl start serena.service

# サービス状態確認
sudo systemctl status serena.service

# ログ確認
sudo journalctl -u serena.service -f

🎯 用途別推奨方法

🪟 Windows版バックグラウンド起動ガイド

Windows重要注意事項

tmuxはWindows単体では動作しません！
LinuxやmacOSのようなUnix系OSでのみ利用可能です。
WindowsでLinux系ツールを使うには WSL または Git Bash が必要です。

🚀 PowerShell + Start-Process

Windows標準のPowerShellを使用した最もシンプルな方法

Start-Process powershell -ArgumentList "-Command", "uvx --from git+https://github.com/oraios/serena serena start-mcp-server" -WindowStyle Hidden

🛠️ WSL + tmux (推奨)

Windows Subsystem for Linux内でLinuxツールを活用

# WSLに入る
wsl

# tmuxセッション作成
tmux new -s serena

# UVコマンド実行
uvx --from git+https://github.com/oraios/serena serena start-mcp-server

# デタッチ: Ctrl + b → d

⚙️ タスクスケジューラ

1. Win + R → taskschd.msc
2. 「基本タスクの作成」
3. トリガー: システム起動時
4. 操作: プログラムの開始
5. プログラム: uvx
6. 引数: --from git+https://github.com/oraios/serena serena start-mcp-server

🏆 Windowsでのベストプラクティス

開発・テスト環境: WSL + tmux が最強の組み合わせ
本番・サーバー環境: タスクスケジューラ + PowerShell で安定運用
お手軽テスト: PowerShell Start-Process で即座に実行

3. より高度な使い方

プロジェクトのインデックス化

大規模なプロジェクトでSerenaの真価を発揮させるには、事前にコードをインデックス化（構造を解析・整理）しておくことが推奨されます。

# 例: /path/to/your/project をインデックス化する場合
serena project index /path/to/your/project

注意: 旧コマンド index-project は廃止されました。serena project index を使用してください。

Windowsでのuvインストール詳細

winget install --id astral-sh.uv

🔽 このコマンドでインストールされるもの

Serenaの設定ファイル保存場所

Serenaを起動すると、ユーザーディレクトリ直下に .serena フォルダが自動生成されます。

Windows:

C:\Users\<ユーザー名>\.serena\

Linux/WSL:

/home/<ユーザー名>/.serena/

この .serena フォルダには以下が保存されます：

• serena_config.yml … グローバル設定ファイル
• language_servers/ … 言語サーバーのキャッシュや実行バイナリ
• logs/ … ログファイル
• prompt_templates/ … プロンプトやモードの定義

重要: これは実行ファイルの設置場所ではなく、設定やキャッシュの保存場所です。

4. こんな人におすすめ

• 大規模なコードベースを扱う開発者
• AIに毎回長文のコードをコピー＆ペーストするのが面倒だと感じている人
• セキュリティやプライバシーを重視し、ローカル環境で作業を完結させたい人
• AIとの対話で**「文脈が足りない」と感じることが多い**人
• ターミナル操作の学習コストを下げたいと考えている人

5. Claude Codeとの連携

プロジェクトディレクトリで以下のコマンドを実行：

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

初期設定の読み込み：

Serenaの初期設定を読み込んでください

または：

/mcp__serena__initial_instructions

プロジェクトの有効化：

絶対パスで指定:

プロジェクト /path/to/my_project を有効化してください

プロジェクト名で指定（過去に有効化済みの場合）:

プロジェクト my_project を有効化してください

6. ChatGPTとの連携について（重要な訂正）

⚠️ 重要：公式ChatGPTは現在MCPを直接サポートしていません

2025年8月現在、OpenAIの公式ChatGPT（Web版、モバイルアプリ、デスクトップアプリ）はMCP（Model Context Protocol）を直接サポートしていません。 OpenAIはChatGPTデスクトップアプリでのMCPサポートを開発中と発表していますが、まだリリースされていません。

現在の選択肢

オプション1：MCP SuperAssistant Chrome拡張機能（サードパーティ）

Chrome拡張機能「MCP SuperAssistant」を使用してWebベースのChatGPTでMCP機能を有効にできます：

1. Chrome Web Storeで「MCP SuperAssistant」を検索してインストール
2. ローカルプロキシサーバーを設定
3. 拡張機能のサイドバーから接続

注意：これはサードパーティ製のソリューションであり、OpenAIの公式サポートではありません。

オプション2：OpenAI Agents SDK（開発者向け）

OpenAIはPython用のAgents SDKでMCPサポートをリリースしています：

• MCP サーバーをOpenAI Agentsに接続可能
• プログラミング知識が必要
• 一般ユーザー向けのGUIソリューションではない

✅ 現時点での推奨事項

Serenaを使いたい場合、最も信頼できる選択肢は：

1. Claude Desktop または Claude Code（完全サポート）
2. Cursor IDE のMCP統合
3. VS Code と Cline拡張機能
4. Gemini CLI の適切なMCP設定

7. Gemini CLIとの連携

MCP サーバーの登録が必須

Gemini CLIでSerenaを使うには、まず Gemini CLI に Serena の MCP サーバーを登録する必要があります。

設定ファイル

プロジェクト側 <project>/.gemini/settings.json（またはグローバル ~/.gemini/settings.json）：

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

動作確認の手順

1. uvx -V が通るか確認
2. Geminiをプロジェクトルートで起動 → /mcp reload → /mcp list
3. serena - Connected (… tools cached) になればOK

8. Serenaがサポートしている言語（2025年8月時点）

✅ サポート言語

❌ 非対応

PowerShellスクリプトなどを扱う方法

非対応ファイルも「読み取り対象」として含めることは可能です。

project.yml の例：

project_name: myproject
language: python  # ダミー（何でもよい）
include:
  - "**/*.ps1"
  - "**/*.bat"

9. Python バージョンの互換性

10. よくある質問（FAQ）

Q. GPUは必要ですか？

A. Serena自体はCPUで動作します。LLM側（例：ローカルLlama）でGPUが必要な場合は別途検討してください。

Q. トークン節約の具体例は？

A. 300ファイル以上のプロジェクトで、毎回50KB送信 → インデックス後は4KB未満に削減。Claude Proの月額制限で計算すると、約**92%**の削減になります。

Q. Windowsで動作しますか？

A. はい、uvxはWindowsで動作します。パス区切り文字に注意（C:\path\to\uvx）。

Q. ChatGPTのサポートはいつ利用可能になりますか？

A. OpenAIはChatGPTデスクトップアプリのMCPサポートを開発中と発表していますが、リリース日は未定です（2025年8月現在）。

まとめ

Serenaは、ローカル環境でAIと安全に連携できる強力なツールです。特にプライバシーを重視する開発現場や、大規模なコードベースを扱うプロジェクトで威力を発揮します。現時点では Claude Desktop/Code、Cursor、Gemini CLI との統合が最も安定していますが、将来的にはChatGPTでも公式サポートが期待されています。