AIコーディングエージェントにコードベースを読ませるとき、ファイルを丸ごと読み込ませたりgrep的な文字列検索をさせたりすると、トークンを大量に消費したり、関数やクラスの境界を無視した曖昧な一致が混ざったりします。この隙間を、言語サーバー（LSP）を使った「シンボル単位」のコード検索・編集ツールで埋めるオープンソースのMCPツールキットが、Oraios AIが開発する「Serena」です。公式リポジトリは自らを「the IDE for your agent」と位置づけており、READMEにはMicrosoftのVS CodeチームとOpen Source Programs Office、GitHub Open Sourceから一度限りのスポンサー支援を受けたことも明記されています。
この記事は、公式GitHubリポジトリ（oraios/serena）のREADMEとdocs/配下の各ドキュメント、およびPyPIの公開パッケージ情報（pypi.org/pypi/serena-agent/json）を一次情報としています。実際にこのクラウド環境へ公式の手順どおりuv tool installでインストールし、インストール結果と、インストールされたパッケージ内に実際に存在するPythonのツール実装クラスを確認しました。一方で、この検証環境の実行ポリシー上、インストール後にserenaコマンド自体を起動すること（MCPサーバーの起動、プロジェクトのactivate、ツール呼び出しの実行など）はできませんでした。そのため、MCPサーバーが実際に起動する様子やツール呼び出しの応答は確認できておらず、本文ではその区別を明記します。
Serenaとは：エージェントに「シンボル単位の目」を与えるMCPサーバー
READMEによると、Serenaは「essential semantic code retrieval, editing, refactoring and debugging tools」を、MCP経由で任意のクライアント・LLMに提供するツールキットです。ファイル全体やgrep結果をLLMに渡す代わりに、言語サーバーが持つシンボル情報（クラス・関数・参照関係など）をそのまま使わせることで、少ないトークンで正確なコード操作ができる、という設計思想です。Claude Code・Claude Desktop・Codex・VS Code・JetBrains IDEなど複数のクライアントとの連携が前提になっています。
実際にuv tool installでインストールした
READMEが案内するインストール方法はuvを前提にしたこの1行のみで、「MCPやプラグインのマーケットプレイス経由でインストールしないでください」と明記されています。
uv tool install -p 3.13 serena-agentこのクラウド環境にはuvとpython3.13がすでに入っており、実際に上記コマンドをそのまま実行しました。エラーなく完了し、最終的なログには次のとおり表示されました。
Installed 3 executables: serena, serena-agent, serena-hooksインストールされたパッケージのメタデータ（dist-info/METADATA）を確認すると、バージョンは2.1.0、作者はOraios AI <info@oraios-ai.de>、ライセンス表記はGPL-3.0-or-laterでした。同じ内容はPyPIの公開API（pypi.org/pypi/serena-agent/json）が返すinfo.version・info.license_expressionとも一致しており、サマリー文「A powerful MCP toolkit for coding, providing semantic retrieval and editing capabilities - the IDE for your agent」もREADMEの説明と揃っています。なお、READMEのインストール手順は-p 3.13でPython 3.13を指定していますが、実際のメタデータのRequires-Pythonは<3.15,>=3.11で、3.11以上であれば動く設計のようです（READMEが3.13を指定しているのは推奨バージョンという位置づけと考えられます）。
公開ツールの実体をインストール済みのソースコードで確認
CLI自体の起動は実行ポリシー上できませんでしたが、uv tool installでインストールされたパッケージは、このクラウド環境のディスク上に実ファイルとして展開されています。そこで、serena/tools/配下のPythonソースを実際に読み、ドキュメントが説明するツール群が実装としても存在するかを確認しました。class定義をそのまま拾うと、次のようなツールクラスが見つかりました。
- symbol_tools.py：
GetSymbolsOverviewTool・FindSymbolTool・FindReferencingSymbolsTool・FindImplementationsTool・FindDeclarationTool・GetDiagnosticsForFileTool・GetDiagnosticsForSymbolTool・ReplaceSymbolBodyTool・InsertAfterSymbolTool・InsertBeforeSymbolTool・RenameSymbolTool・SafeDeleteSymbol・RestartLanguageServerTool（シンボルの取得・参照検索・実装検索・診断・シンボル単位の編集） - file_tools.py：
ReadFileTool・ListDirTool・FindFileTool・SearchForPatternTool・ReplaceContentTool・ReplaceInFilesTool・DeleteLinesTool・ReplaceLinesTool・InsertAtLineTool・CreateTextFileTool（ファイル単位・行単位の基本操作。公式ドキュメントはClaude CodeやCodexのような既に強力なファイル操作を持つハーネスでは、これらの基本ツールを無効化しておく運用を想定しています） - memory_tools.py：
WriteMemoryTool・ReadMemoryTool・ListMemoriesTool・DeleteMemoryTool・RenameMemoryTool・EditMemoryTool（プロジェクトに関する知識をメモリファイルとして保存・参照する） - workflow_tools.py：
OnboardingTool・InitialInstructionsTool・SerenaInfoTool - config_tools.py：
ActivateProjectTool・RemoveProjectTool・GetCurrentConfigTool・OpenDashboardTool
いずれも公式ドキュメント（docs/）が説明する「retrieval」「symbolic editing」「basic tools」「memory」のカテゴリ分けと一致しており、マーケティング文面だけでなく実装としても裏付けが取れました。
Claude Codeへの組み込み方
公式ドキュメントdocs/02-usage/030_clients.mdには、Claude Code向けの設定方法が具体的に書かれています。自動セットアップは次の1コマンドです。
serena setup claude-code手動で設定する場合、全プロジェクト共通なら次のようにclaude mcp addを使います。
claude mcp add --scope user serena -- serena start-mcp-server --context claude-code --project-from-cwd特定プロジェクトだけに限定する場合は、カレントディレクトリを明示して次のように登録します。
claude mcp add serena -- serena start-mcp-server --context claude-code --project "$(pwd)"いずれも--context claude-codeフラグでクライアントの種類を伝えており、設定後はClaude Code内で/mcpを実行して接続を確認します。起動が遅い場合はMCP_TIMEOUT環境変数を大きくする（例：export MCP_TIMEOUT=60000）ことも案内されています。さらに、.claude/settings.json（プロジェクト単位）や~/.claude/settings.json（全体）にフックを追加することで、serena-hooks remind・serena-hooks auto-approve（mcp__serena__*にマッチ）・serena-hooks activate（SessionStart）・serena-hooks cleanup（SessionEnd）といった挙動を組み込める設計になっています。VS CodeやCodex（CLI/App）向けにも、それぞれ--context=vscode・--context=codexを使う同様の手順が用意されていました。
プロジェクトのワークフロー：作成・activate・オンボーディング・インデックス
docs/02-usage/040_workflow.mdによると、Serenaを使う流れは次のようになっています。
- プロジェクトディレクトリで
serena project createを実行する（省略してチャット中に「このプロジェクトをactivateして」と頼むだけでも既定設定で動く）。この時点で.serena/ディレクトリと設定ファイル.serena/project.ymlが作られる - MCPサーバー起動時に
--project <path|name>を渡すか、チャット内でactivate_projectツールを呼んでプロジェクトを有効化する - そのプロジェクトで初めて起動したとき、既定でオンボーディングが走り、プロジェクトの規約などをメモリファイルとして書き出す（
mem:NAMEという形式で他のメモリを相互参照できる） - 大規模なプロジェクトでは
serena project indexを1度実行しておくと、言語サーバーのシンボル情報が事前にキャッシュされ、最初のシンボル系ツール呼び出しが遅くならない。以降はファイル変更に応じて自動更新される
GPLとMITを行き来したライセンスの経緯
docs/01-about/060_license.mdには、やや珍しいライセンス構成の理由が説明されています。言語サーバーとの通信を担うライブラリ部分「SolidLSP」（src/solidlsp）はMITで、他のプロジェクトにも自由に組み込めるようにあえて緩いライセンスにしているとのことです。一方、エージェント本体・ツール・MCPサーバー・プロンプトなどの「Serenaアプリケーション」部分はGPL-3.0-or-laterです。ドキュメントは「Serenaの最良のバージョンをフリー（自由）なままにしておきたい」という方針を掲げ、GPLであれば派生版を再配布する側も同じ自由をユーザーに残さざるを得ない、という理由を挙げています。さらに興味深いのは経緯で、プロジェクトは元々GPLで始まり、コミュニティの要望でいったんMITに移行したものの、後にその判断を「誤りだった」と結論づけ、v2のアーキテクチャ変更に合わせてアプリケーション部分をGPLに戻したとされています。serena-agentのようにSolidLSPとアプリケーションを組み合わせて配布するパッケージは、全体としてGPL-3.0-or-laterに従うことになります。
対応言語の幅：ドキュメント上は60以上、README本文は「40以上」
docs/01-about/020_programming-languages.mdには、Ada/SPARK・Go（gopls）・Rust（rust-analyzer）・Python（Pyright、BasedPyright、ty、pyrefly、Jediなど複数選択可）・TypeScript・C/C++（clangd・ccls）・Java・Kotlin（pre-alpha）・Terraform・YAML・Lean 4・Nextflow・GDScript（Godotエディタ起動が前提）まで、60以上の言語・言語サーバーの組み合わせが表として列挙されています。Angular・Ansible・GraphQL・HTML・JSON・LaTeX・SCSS/Sass/CSS・Solidity・TOML・Denoは「experimental」、Kotlin用サーバーは「pre-alpha」と明記されており、すべてが同じ完成度ではない点も書かれていました。一方でREADME本文の説明文では「over 40 languages」とされており、個別ページの表の規模とREADMEの文言には差があります。どちらも公式の記述である以上、導入前には使う言語が表の中でどの成熟度に分類されているかを確認したほうが安全そうです。
向いている場面・向いていない場面
- 向いている：Claude CodeやCodexのような既存のAIコーディングエージェントに、言語サーバーベースの正確なシンボル検索・編集能力を追加したい場合。大規模なコードベースで、ファイル全読みやgrepによるトークン消費を減らしたい場合
- 向いていない：アプリケーション部分はGPL-3.0-or-laterのため、プロプライエタリな製品に組み込んで配布することを考えている場合は、ライセンス条件を事前に確認する必要があります。また対応言語ごとに言語サーバーの成熟度が大きく異なるため、experimentalやpre-alpha表示の言語を主軸にする場合は不具合を踏む前提で試すほうが安全です
この記事で確認できなかったこと
繰り返しになりますが、この検証ではuv tool installによるインストールと、インストールされたパッケージのメタデータ・Pythonソースコードの確認までを実際に行いました。この環境の実行ポリシー上、serenaコマンド自体の起動、MCPサーバーとしての接続、プロジェクトのactivateやオンボーディング、シンボル検索・編集ツールの実際の呼び出しと応答は確認できていません。Claude Codeへの登録手順やワークフローに関する記述は、公式ドキュメントの記載に基づくものであり、実際の挙動は手元の環境やプロジェクトの規模によって変わる可能性があります。
まとめ
Serenaは、AIコーディングエージェントに言語サーバーベースのシンボル単位の検索・編集能力を与えるオープンソースのMCPツールキットです。実際にこのクラウド環境へ公式手順のuv tool install -p 3.13 serena-agentでインストールし、バージョン2.1.0が問題なく導入されたこと、ドキュメントが説明するツール群（シンボル検索・編集、ファイル操作、メモリ、プロジェクト管理）がインストール済みのPythonソースコード上にも実装として存在することを確認できました。一方で、MCPサーバーとしての起動やClaude Codeからの実際のツール呼び出しはこの検証環境では試せていません。GPLとMITを併用するやや特殊なライセンス構成や、対応言語ごとの成熟度の違いもあるため、導入前には公式ドキュメントの該当ページを確認しておくのが安全です。
参考にした一次情報
- GitHub公式リポジトリ：oraios/serena（README、ライセンス、スポンサー表記）
- docs/02-usage/030_clients.md（Claude Code・VS Code・Codexへの組み込み手順）
- docs/02-usage/040_workflow.md（プロジェクトのワークフロー、オンボーディング、インデックス）
- docs/01-about/060_license.md（GPL/MITのライセンス方針と経緯）
- docs/01-about/020_programming-languages.md（対応言語と言語サーバーの一覧）
- PyPI公開API：serena-agent（バージョン、ライセンス表記、サマリー）
- 本文中の
uv tool installの実行結果・インストール済みパッケージのメタデータおよびPythonソースコードの内容は、この記事の検証時点で実際にこのクラウド環境でserena-agent 2.1.0をインストールして得たものです。
