Contents
Mastra Studio ローカル環境構築のステップバイステップガイド
AIエージェント開発者は、ローカルでMastra Studioを動作させる際に頻繁に悩みます。2026年以降のバージョンでは、Elasticsearchとの連携やVS Codeでのデバッグ環境構築が推奨されるケースが多いですが、プロジェクト要件によっては省略可能です。本記事では、公式ドキュメントに基づいた具体的な手順とトラブルシューティングを解説します。
ローカル環境構築に必要な前提条件
Mastra Studioをローカルで動かすには、Node.jsやElasticsearchといった前提ソフトウェアが推奨されます。導入方法とOSごとの手順を確認してください。
Node.jsとnpmのインストール確認
Node.js 20.x以上とnpm 10.x以上は必須です。以下のコマンドでバージョンを確認してください。
|
1 2 3 |
node -v npm -v |
- Windowsユーザー: Node.js公式サイトからインストーラーをダウンロード
- macOS/Linuxユーザー:
nvmを使ってバージョン管理を推奨します
注意: インストール後、環境変数（PATH）の設定が正しくない場合にエラーが発生する可能性があります。
Elasticsearchの事前導入手順
Elasticsearchは検索機能のためのオプションツールです。必要に応じてインストールしてください。
| ステップ | 内容 | 注意点 |
|---|---|---|
| 1 | Elasticsearch公式サイトから最新版をダウンロード | Java 17以上が必要 |
| 2 | ダウンロードしたファイルを解凍し、bin/elasticsearchで起動 |
localhost:9200にアクセス可能か確認 |
| 3 | Elasticsearchのユーザー認証設定（必要に応じて） | 詳細は公式ドキュメントを参照 |
警告: セキュリティ設定で
your_passwordなどのプレースホルダを使用しないように注意してください。
ローカルプロジェクトの初期化手順
プロジェクト作成にはmastra initコマンドが使われます。このステップで構造を作り、設定ファイルを確認します。
mastra initコマンドの実行
以下のコマンドをプロジェクトフォルダ内で実行してください。
|
1 2 |
npx mastra init |
- オプション指定例:
--template=ai-agentでAIエージェント用テンプレートを採用 - プロジェクト名やディレクトリ構成は、初期化時にプロンプトで尋ねられます
生成された設定ファイルの確認
mastra init実行後、以下のようなファイルが自動生成されます。
|
1 2 3 4 5 6 |
. ├── .env # 環境変数設定ファイル（**セキュリティ注意**） ├── mastra.config.js # プロジェクト設定ファイル └── src/ └── agents/ # エージェント定義ファイル |
.envにはElasticsearchの接続情報など記載ELASTICSEARCH_PASSWORD=<<PASSWORD>>とセキュリティ対策を施してください（Gitに含めない）mastra.config.jsでエージェントの動作モードを指定可能
ローカルサーバーの起動とポート確認
プロジェクト初期化後は、ローカルサーバーを起動し、localhost:4111にアクセスします。
startコマンドの実行
以下でサーバーを起動してください。
|
1 2 |
npm run start |
- 起動ログに
Server running at http://localhost:4111と表示されるまで待ちます - ポート衝突が発生した場合は、
lsof -i :4111でプロセスを確認し、停止させてください
localhost:4111へのアクセステスト
ブラウザやPostmanでhttp://localhost:4111/healthにアクセスし、応答が正常か確認してください。異常な場合の対処法は以下です。
| エラーメッセージ | 対処法 |
|---|---|
ECONNREFUSED |
Elasticsearchが起動していない可能性あり |
ENOENT |
プロジェクトディレクトリに必要なファイルが不足 |
VS Codeとの連携設定
VS Codeは、Mastra Studio開発の標準エディタです。デバッグ環境構築と拡張機能利用が重要です。
拡張機能のインストール
VS Codeで以下を実行してください。
|
1 2 |
npm install --save-dev vscode-language-server-stdio |
注意: このコマンドは言語サーバーのサポートに使用されるため、VS Code自体と直接関係ありません。推奨拡張機能をインストールしてください。
- 推奨拡張機能:
- ESLint（コード品質管理）
- Prettier（フォーマット自動化）
デバッグ構成ファイルの作成
.vscode/launch.jsonに以下を記述し、デバッグ用設定を作成します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
{ "version": "0.2.0", "configurations": [ { "type": "node", "request": "launch", "name": "Launch Mastra", "runtimeExecutable": "npm", "runtimeArgs": ["run", "start"], "console": "integratedTerminal" } ] } |
- デバッグ開始は、VS Codeのデバッガー画面から「Launch Mastra」を選択
Elasticsearchとの統合設定
Elasticsearchとの連携はプロジェクト要件に応じて選択可能です。
接続先の設定ファイル編集
.envファイルに以下のように設定してください。
|
1 2 3 4 |
ELASTICSEARCH_HOST=http://localhost:9200 ELASTICSEARCH_USER=elastic ELASTICSEARCH_PASSWORD=<<PASSWORD>> # 実際のパスワードを入力（**Gitに含めない**） |
- パスワードはElasticsearchの初期設定時に発行されたものを使用
検索機能の動作確認
以下のコマンドで検索機能をテストします。
|
1 2 |
npm run search-test |
- 成功時は「Index created successfully」と表示される
- エラー発生時の例:
Elasticsearch exception [type=security_exception]→ ユーザー認証が不正
よくあるトラブルシューティング
ローカル環境構築時にありがちなエラーとその解決策をケーススタディ形式で解説します。
ポート占用時の対処法
症状: Error: listen EADDRINUSE: address already in use
原因: 他のプロセスが4111ポートを使用中
|
1 2 3 |
lsof -i :4111 # 使用中のプロセスを確認 kill -9 <PID> # 不要なプロセスを終了 |
依存モジュールの再インストール
症状: error: cannot resolve module
対処法: ノードモジュールを再インストールします。
|
1 2 3 |
rm -rf node_modules npm install |
- 無理やり実行しても解決しない場合は、プロジェクトディレクトリを再作成することを検討してください。手順:
- 現在のプロジェクトフォルダをバックアップ
- 新しいディレクトリを作成
mastra initで初期化し直す
まとめ
本記事では、Mastra Studioのローカル環境構築に必要な以下の手順を解説しました。
- Node.jsとElasticsearch（推奨）の導入 → プロジェクト起動の前提
mastra initコマンドによるプロジェクト初期化 → 標準的なディレクトリ構成localhost:4111へのアクセステスト → サーバーが正常に動作しているか確認- VS Codeとの連携設定 → デバッグ環境の整備
- Elasticsearch（推奨）との統合設定 → 検索機能の活用
- トラブルシューティング → よくあるエラーの対処法
これらの手順に従って実装することで、AIエージェント開発の効率が向上します。公式ドキュメントを参照しつつ、本ガイドに従ってローカル環境構築を開始してください。
重要事項の再確認
- Elasticsearchとの連携はプロジェクト要件によって選択可能です（2026年以降も同様）
.envファイルにはセキュリティリスクが伴うため、実際の値はGitに含めないように注意- VS Codeでのデバッグ環境構築には「
vscode-language-server-stdio」は補助的な役割を果たす（主なツールは拡張機能） - トラブルシューティングの際、プロジェクトディレクトリ再作成の手順を明確に記載