MCPサーバ - Serena

提供: MochiuWiki : SUSE, EC, PCB

概要

Serenaは、Oraios AIが開発したオープンソース (MITライセンス) のコーディングエージェントツールキットである。
LLMをコードベース上で動作する完全機能のエージェントに変える強力なツールであり、Model Context Protocol (MCP) とLanguage Server Protocol (LSP) を統合して、IDE的なセマンティック解析・コード編集機能を提供する。

Serenaは、従来のテキスト検索ベースのアプローチとは異なり、シンボルレベルでコード要素を理解する。

以下に示すような機能を提供する。

  • IDE的なセマンティック解析機能 (find_symbol、find_referencing_symbols、get_symbols_overview等)
  • シンボル単位のコード編集機能 (replace_symbol_body、insert_after_symbol、insert_before_symbol等)
  • プロジェクト固有のメモリ機能 (write_memory、read_memory、list_memories)
  • シェルコマンド実行とWebダッシュボード (execute_shell_command、open_dashboard)


Serenaを使用することにより、LLMがコンテキストウィンドウのトークン使用量を約38〜80[%]削減しながら、高精度なコード解析・編集を行うことができる。

40以上のプログラミング言語に対応しており、Claude Code、Claude Desktop、VS Code、Cursor、JetBrains AI Assistant等の主要なMCPクライアントと統合できる。

SerenaはMITライセンスで公開されており、最新バージョンはv0.1.4である。


動作要件

システム要件

  • Python 3.11〜3.12
    Python 3.13は現時点では非対応
  • uv (Rust製の高速Pythonパッケージマネージャー)
  • 対応OS
    Windows、MacOS、Linux、Docker


対応MCPクライアント

対応MCPクライアント一覧
クライアント 説明
Claude Desktop Anthropic公式デスクトップアプリケーション
Claude Code AnthropicのCLIツール
VS Code (GitHub Copilot) MicrosoftのエディタとGitHub Copilot統合
Cursor AI機能統合型コードエディタ
Windsurf Codeium製AIコードエディタ
OpenCode Go言語製のターミナルベースAIコーディングアシスタント
JetBrains AI Assistant JetBrains IDE向けAIアシスタント
その他 Antigravity等のMCP対応クライアント



uvのインストール

SerenaはPythonパッケージマネージャーのuvを必要とする。
以下に示すOSごとのインストール方法を参照すること。

Linux

curlを使用してインストールする。

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


MacOS

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


Homebrewの使用
brew install uv


Windows

PowerShellの使用
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"


wingetの使用
winget install --id=astral-sh.uv -e


scoopの使用
scoop install main/uv



Serenaのインストール

uvxを使用する場合 (推奨)

uvx を使用することにより、リポジトリをクローンせずに最新版のSerenaを直接実行できる。
クイックな試験やCI/CDパイプラインに最適な方法である。

動作確認コマンドを以下に示す。

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


リポジトリをクローンする場合

ローカルにリポジトリをクローンして使用する場合の手順を以下に示す。

 git clone https://github.com/oraios/serena.git
 cd serena
 cp src/serena/resources/serena_config.template.yml serena_config.yml


Dockerを使用する場合

Dockerコンテナを使用してSerenaを起動する場合のコマンドを以下に示す。

docker run --rm -i --network host -v /path/to/projects:/workspaces/projects ghcr.io/oraios/serena:latest serena start-mcp-server --transport stdio


/path/to/projectsには、実際のプロジェクトディレクトリのパスを指定すること。


MCPクライアントの設定

Claude Desktop

Claude Desktopの設定ファイルを編集する。

設定ファイルの場所は、以下の通りである。

  • MacOS
    ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows
    %APPDATA%\Claude\claude_desktop_config.json


設定例を以下に示す。

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


設定ファイルを編集した後は、Claude Desktopを再起動する必要がある。

Claude Code

Claude Codeでは、以下のコマンドを実行してSerenaをMCPサーバとして追加する。

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


または、プロジェクトルートに.mcp.jsonファイルを作成して設定する方法もある。

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


VS Code (GitHub Copilot)

VS Codeでは、.vscode/mcp.jsonファイルを作成して設定する。

 {
    "servers": {
       "oraios/serena": {
          "type": "stdio",
          "command": "uvx",
          "args": [
             "--from",
             "git+https://github.com/oraios/serena",
             "serena",
             "start-mcp-server",
             "--context",
             "ide",
             "--project",
             "${workspaceFolder}"
          ]
       }
    }
 }


Cursor / Windsurf

CursorおよびWindsurfでは、--context ide 引数を指定することにより、IDE側のツールと重複する機能を無効化できる。

設定例を以下に示す。

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


OpenCode

OpenCodeは、Go言語で構築されたターミナルベースのAIコーディングアシスタントである。
複数のAIプロバイダー (OpenAI、Claude、Google Gemini等) をサポートしている。

設定ファイルの場所は、以下の通りである。

  • グローバル設定
    ~/.config/opencode/opencode.json
  • プロジェクト設定
    /<プロジェクトのパス>/opencode.json


設定例を以下に示す。

 {
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
       "serena": {
          "type": "local",
          "command": [
             "uvx",
             "--from",
             "git+https://github.com/oraios/serena",
             "serena",
             "start-mcp-server",
             "--context",
             "ide-assistant"
          ],
          "environment": {
             "PYTHONUNBUFFERED": "1"
          }
       }
    }
 }


OpenCodeでは、--context ide-assistant を指定することにより、IDE側のツールとの重複を避けることが推奨される。

設定ファイルを作成した後、OpenCodeを起動してSerena MCPサーバが正常に読み込まれたことを確認する。


プロジェクト設定

project.yml

Serenaはプロジェクトごとの設定ファイルを自動生成する。

  • 場所
    /<プロジェクト>/.serena/project.yml
  • 主な設定内容
    使用プログラミング言語の指定
    検索対象ディレクトリの設定
    除外ディレクトリの設定


グローバル設定

SerenaのグローバルなデフォルトはYAML形式の設定ファイルで管理する。

設定ファイルの場所は、以下の通りである。

  • Linux / MacOS
    ~/.serena/serena_config.yml
  • Windows
    %USERPROFILE%\.serena\serena_config.yml


主な設定項目は以下の通りである。

  • ツールの有効・無効設定
  • 言語サーバ固有の設定
  • タイムアウト・回答長などの実行パラメータ
  • ロギング設定


言語サーバのパスをカスタマイズする場合の設定例を以下に示す。

 ls_specific_settings:
    <language>:
       ls_path: "/custom/path"


コンテキスト

コンテキストは、Serena起動時に --context オプションで指定する。
セッション開始後はコンテキストを変更できないため、用途に応じて適切なコンテキストを選択すること。

下表に、利用可能なコンテキストを示す。

コンテキストの一覧
コンテキスト 説明
desktop-app デスクトップアプリケーション向けのデフォルトコンテキスト
フルセットのSerenaツールを提供する。
claude-code Claude Code統合用コンテキスト
Claude Code固有の機能と重複するツールを無効化する。
ide VS Code、Cursor等のIDEアシスタント向けコンテキスト
agent 自律エージェント用コンテキスト
oaicompat-agent OpenAI互換ツール記述対応コンテキスト


モード

モードは複数同時有効化が可能な動作調整ツールである。
起動時に--modeオプションで指定する。

下表に、ビルトインモードに示す。

モードの一覧
モード 説明
planning 計画・分析タスク向けのモード
editing コード修正を最適化するモード
interactive 対話型モード（デフォルト）
one-shot 単一応答で完結するモード
onboarding プロジェクトの初期化・分析向けモード
no-memories メモリツールを無効化するモード


複数のモードを同時に指定する例を以下に示す。

serena start-mcp-server --mode planning --mode no-onboarding



主なツール

コード検索・解析ツール

コード検索・解析ツール
ツール 説明
find_symbol グローバル（またはローカル）シンボルを検索する。
find_referencing_symbols 特定シンボルの参照元を検索する。
get_symbols_overview ファイル内のトップレベルシンボルの概要を取得する。
rename_symbol 全参照箇所を一括でリネームする。


コード編集ツール

コード編集ツール
ツール 説明
replace_symbol_body シンボル定義を完全に置換する。
insert_after_symbol 特定シンボルの後に新しいコードを挿入する。
insert_before_symbol 特定シンボルの前に新しいコードを挿入する。
replace_lines 指定した行範囲を置換する。
replace_content ファイル内容を置換する。(正規表現対応)
delete_lines ファイル内の指定した行範囲を削除する。


ファイル管理ツール

ファイル管理ツール
ツール 説明
read_file プロジェクトディレクトリ内のファイルを読み取る。
create_text_file ファイルを新規作成または上書きする。
list_dir ディレクトリの内容を一覧表示する。


プロジェクト分析ツール

プロジェクト分析ツール
ツール 説明
activate_project プロジェクトを有効化する。
onboarding プロジェクト構造と必須タスクを特定する。
get_current_config 現在のエージェント設定を表示する。


メモリ・その他のツール

メモリ・その他のツール
ツール 説明
write_memory / read_memory / list_memories プロジェクト固有のメモリ機能
execute_shell_command シェルコマンドを実行する。
open_dashboard Webダッシュボードを起動する。
switch_modes セッション内でモードを変更する。


Serenaは上記を含む合計40個以上のツールを提供する。


使用方法

Claude Codeでの使用例

Claude Codeで作業するプロジェクトディレクトリに移動して、MCPサーバとしてSerenaを追加した上でClaude Codeを起動する。

# 使用例 :

コードベースの概要を把握してください。



# 使用例 :

UserAuthクラスのloginメソッドの実装を確認してください。



# 使用例 :

fetchData関数を参照している箇所を全て列挙してください。


Claude Desktopでの使用例

Claude Desktop設定ファイルにSerenaを追加した後、Claude Desktopを再起動して、Serenaツールを利用できる状態にする。

# 使用例 :

@serena このプロジェクトのディレクトリ構造を分析して概要を教えてください。



# 使用例 :

@serena src/api/users.ts のUserServiceクラスにgetAllUsersメソッドを追加してください。


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

Serenaのシンボル検索を活用するために、プロジェクトのインデックスを作成する。

  • 手動でインデックスを作成する場合 
     serena project index

  • 並列処理でインデックスを作成する場合 
     serena project index --parallel 4

  • 差分インデックスを作成する場合 
     serena project index --incremental



対応プログラミング言語

Serenaは40以上のプログラミング言語に対応している。

以下に示す言語は、デフォルト設定で利用可能である。

デフォルト設定で利用可能な言語
言語 言語サーバ
Bash デフォルト
Java デフォルト
JavaScript デフォルト
Python デフォルト
Rust デフォルト
TypeScript デフォルト
YAML デフォルト
Dart デフォルト
Swift デフォルト
Lua デフォルト
Markdown デフォルト
Zig デフォルト
Clojure デフォルト
Elm デフォルト


以下に示す言語は、追加の言語サーバインストールが必要である。

追加インストールが必要な言語
言語 言語サーバ 備考
C / C++ clangd (デフォルト) / ccls compile_commands.jsonが必要
C# Roslyn / OmniSharp .NET 10以上が必須
Go gopls 要インストール
Scala Metals 手動セットアップが必要
Vue - Node.js v18以上が必要
R languageserver Rパッケージが必要
Elixir ElixirLS -
F# FSharp言語サーバ -
Fortran fortls -
Haskell Haskell言語サーバ -
Kotlin Kotlin言語サーバ -
Perl Perl言語サーバ -
PHP Intelephense INTELEPHENSE_LICENSE_KEY設定可
Ruby - 言語サーバが別途必要
Nix Nix言語サーバ -
Pascal pasls FPCコンパイラのパス指定可
Erlang erlang_ls -



トラブルシューティング

接続・起動関連

uvコマンドが見つからないエラーが発生する場合は、以下の項目を確認する。

  • uvがインストールされているか確認
    uv --version コマンドでインストール状態を確認する。
  • PATH設定が正しいか確認
    uvのインストールディレクトリがPATHに含まれているか確認する。
    シェルの設定ファイル (~/.profile、~/.zprofile等) を再読み込みする。


WindowsでSerenaを使用する時に相対パスエラーが発生する場合は、設定ファイル内でプロジェクトパスを絶対パスで指定すること。

Webダッシュボードを使用する場合は、設定ファイルで web_dashboard オプションを有効化する設定が必要である。

Claude統合関連

Serenaのツール呼び出しが動作しない場合は、以下の項目を確認する。

  • FileSystem MCPとのツール名競合を確認
    Claude DesktopでFileSystem MCPサーバを同時に有効化している場合、ツール名が競合することがある。
    Serenaのツール名をユニークにするか、競合するMCPサーバを無効化する。


Claude CodeでSerenaへの接続が失敗する場合は、以下の項目を確認する。

  • タイムアウト設定を確認
    デフォルトのタイムアウト値が短い場合は、設定で延長する。
  • MCPサーバの起動ログを確認
    claude mcp list コマンドで登録されているMCPサーバを確認する。


デバッグ方法

問題が解決しない場合は、以下に示すデバッグ手段を試みること。

  • ログファイルの確認
    SerenaのMCPログ (mcp.log等) を確認する
  • MCP Inspectorの使用
    MCP Inspectorツールを使用してMCPサーバの動作を詳細に確認する。
    npx @modelcontextprotocol/inspector uvx --from git+https://github.com/oraios/serena serena start-mcp-server で起動する。



関連リソース



「https://mochiu.net/index.php?title=MCPサーバ_-_Serena&oldid=14417」から取得