Laravel Telescope MCP

Laravel Telescope の拡張機能です。テレメトリーデータを Model Context Protocol（MCP）経由で AI アシスタント（Cursor、Claude、Copilot Chat など）に公開します。Telescope を使ってアプリケーションのメトリクスを調査し、迅速かつ正確な分析を必要とする開発者に最適です。

概要

Telescope MCP は、Laravel Telescope のすべてのテレメトリーデータを Model Context Protocol（MCP）経由で公開し、AI アシスタントがアプリケーションのメトリクスに直接アクセスして分析できるようにします。自然言語での問い合わせを通じて、ログ、低速なクエリ、HTTP リクエスト、例外、ジョブなどについて、開発者は即座に把握できます。

要件

• PHP 8.3+
• Laravel 11、12 または 13
• Laravel Telescope 5.0+

重要

HTTP MCP エンドポイントは、デフォルトでは認証されていません。オンラインで公開する場合は、まず認証を有効にしてください（「IDE でのセキュアな Streamable HTTP」を参照）。

ステータス：✅ 19 個の MCP ツールがすべて正常に動作し、統合済みです

v1.0 の新機能

🎉 公式の Laravel/MCP パッケージを採用しました！

• Laravel 公式の MCP フレームワークを基盤としており、保守性と長期サポートが向上しています
• Laravel\Mcp\Server\Tool を使った、よりシンプルなツール定義によるアーキテクチャの改善
• JsonSchema ビルダーによるスキーマ検証の強化
• Laravel\Mcp\Request と Laravel\Mcp\Response によるリクエスト処理の改善
• 完全な後方互換性を維持しており、19 個のツールはすべて従来どおり動作します
• 今後の Laravel/MCP 機能（リソース、プロンプト、OAuth 認証）に対応します

クイックスタート

1. パッケージをインストールします：

   composer require lucianotonet/laravel-telescope-mcp --dev
   

2. MCP クライアントを自動設定します：

   php artisan telescope-mcp:install
   

   💡 Cursor、Claude Code、Windsurf、Cline、Gemini App、Antigravity、Codex、OpenCode を自動検出して設定します。

3. IDE／エディターを再起動して、ツールを使い始めましょう！

---

詳細なインストール手順

1. パッケージを追加する

composer require lucianotonet/laravel-telescope-mcp --dev

2. MCP クライアントを設定する

自動インストーラーを使うか、手動で設定できます。

オプション A：自動インストール（推奨）

php artisan telescope-mcp:install

このコマンドは次の処理を行います：

• インストール済みの MCP クライアントを検出します
• 適切な設定ファイル（mcp.json、settings.json など）を生成します
• サーバーを stdio モードで設定します

オプション B：手動設定 次の内容を MCP クライアントの設定ファイルに追加します：

{
  "mcpServers": {
    "laravel-telescope": {
      "command": "php",
      "args": ["artisan", "telescope-mcp:server"],
      "cwd": "/path/to/your/project",
      "env": {
        "APP_ENV": "local"
      }
    }
  }
}

重要

Antigravity をお使いの場合： Antigravity は cwd プロパティをサポートしていません。args 配列内では artisan の絶対パスを使用する必要があります。また、env オブジェクトに "MCP_MODE": "stdio" を追加することを推奨します。

3. インストールを確認する

サーバーを手動で実行し、正常に動作することを確認します：

php artisan telescope-mcp:server

サーバーは何も表示せずに（stderr にログを出力しながら）起動し、JSON-RPC 入力を待機します。

---

アシスタントごとの手動設定

手動で設定する場合は、次の内容をアシスタントの設定ファイルに追加します：

Cursor、Windsurf、Cline

ファイル： mcp.json または cline_mcp_settings.json

{
  "mcpServers": {
    "laravel-telescope": {
      "command": "php",
      "args": ["artisan", "telescope-mcp:server"],
      "cwd": "/absolute/path/to/your/project",
      "env": {
        "APP_ENV": "local"
      }
    }
  }
}

Claude Code（CLI）

~/.claude/mcp.json ファイル（Cursor と同じ形式）または次のコマンドで設定できます：

claude mcp add -s local -t stdio laravel-telescope php artisan telescope-mcp:server

Antigravity

ファイル： mcp_config.json（グローバル設定のみ）

{
  "mcpServers": {
    "laravel-telescope": {
      "command": "php",
      "args": ["/absolute/path/to/your/project/artisan", "telescope-mcp:server"],
      "env": {
        "APP_ENV": "local",
        "MCP_MODE": "stdio"
      }
    }
  }
}

OpenCode

OpenCodeでは異なるキーを使用し、artisan の絶対パスが必要です。

ファイル： opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "laravel-telescope": {
      "type": "local",
      "enabled": true,
      "command": ["php", "/absolute/path/to/your/project/artisan", "telescope-mcp:server"],
      "environment": {
        "APP_ENV": "local"
      }
    }
  }
}

Codex（TOML）

ファイル： config.toml

[mcpServers.laravel-telescope]
command = "php"
args = ["artisan", "telescope-mcp:server"]
cwd = "/absolute/path/to/your/project"

[mcpServers.laravel-telescope.env]
APP_ENV = "local"

トラブルシューティング（Stdio）

PHP または Artisan が見つからない

php がグローバルの PATH に含まれていることを確認するか、PHP 実行ファイルの絶対パスを使用してください。Windows では、JSON/TOML のパスに二重バックスラッシュ \\ を使用してください。

権限

AI アシスタントが、Telescope がデータを保存する Laravel プロジェクトの storage ディレクトリに対する読み取り／書き込み権限を持っていることを確認してください。

MCP ログ

ツールが表示されない場合は、アシスタントのエラーログ（例：Cursor の出力 > MCP）を確認してください。ターミナルで手動実行したときに、コマンド php artisan telescope-mcp:server がエラーなく実行される必要があります。

MCP Inspector の使用（ブラウザー UI／HTTP）

@modelcontextprotocol/inspector を使用してブラウザーからサーバーをテストする場合は、MCP エンドポイント URL で HTTP トランスポートを使用してください。

1. リモート／公開エンドポイントに対して Inspector を起動する

npx -y @modelcontextprotocol/inspector --transport http --server-url "https://your-domain.com/telescope-mcp"

2. ローカル HTTPS エンドポイントに対して Inspector を起動する

ローカル証明書が自己署名証明書（*.test ドメインでよくあります）の場合は、現在のシェルで Node の TLS 検証を無効にしてください。

# PowerShell
$env:NODE_TLS_REJECT_UNAUTHORIZED='0'
npx -y @modelcontextprotocol/inspector --transport http --server-url "https://your-local-domain.test/telescope-mcp"

3. Inspector のデフォルトポートが使用中の場合

Inspector はデフォルトでポート 6274（UI）と 6277（プロキシ）を使用します。「PORT IS IN USE」と表示された場合：

# PowerShell
$env:CLIENT_PORT='6284'
$env:SERVER_PORT='6287'
npx -y @modelcontextprotocol/inspector --transport http --server-url "https://your-domain.com/telescope-mcp"

4. 認証ヘッダー（任意）

MCP ルートがミドルウェアで保護されている場合は、ヘッダーを渡してください。

npx -y @modelcontextprotocol/inspector --transport http --server-url "https://your-domain.com/telescope-mcp" --header "Authorization: Bearer YOUR_TOKEN"

5. 簡易ヘルスチェック

• GET /telescope-mcp が 405 を返すのは想定どおりです。
• MCP JSON-RPC リクエストには POST /telescope-mcp を使用してください。

IDE でのセキュアな Streamable HTTP

このパッケージは、HTTP MCP エンドポイント用の組み込みベアラートークン認証に対応しました。

1. Laravel で認証を有効にする（.env）

MCP_BEARER_TOKEN=replace-with-a-long-random-token

MCP_BEARER_TOKEN の代わりに TELESCOPE_MCP_BEARER_TOKEN も使用できます。 これらのトークン用環境変数のいずれかが設定されている場合、認証は自動的に有効になります。 明示的に制御する場合は、次のように設定してください。

TELESCOPE_MCP_AUTH_ENABLED=true

トークンの生成例：

php -r "echo bin2hex(random_bytes(32)), PHP_EOL;"

2. IDE UI のマッピング（Streamable HTTP）

次のようなフィールドを求める IDE の場合：

• Name
• Streamable HTTP
• URL
• Bearer token env var
• Headers / Headers from environment variables

次のように設定してください。

• Name：laravel-telescope-online（または任意の名前）
• Transport：Streamable HTTP
• URL：https://your-domain.com/telescope-mcp
• Bearer token env var：MCP_BEARER_TOKEN

IDE が「Bearer token env var」に対応していない場合は、ヘッダーを手動で設定してください。

• Key：Authorization
• Value：Bearer <your-token>

IDE が「headers from env variables」に対応している場合は、次の設定を推奨します。

• Key：Authorization
• Value：Bearer ${MCP_BEARER_TOKEN}

3. ローカルとオンラインの例

• ローカル URL：https://your-local-domain.test/telescope-mcp
• オンライン URL：https://your-public-domain.com/telescope-mcp

参考資料：OpenAI Codex MCP ドキュメント（https://developers.openai.com/codex/mcp/）。

使用方法

接続後は、AI アシスタントで MCP ツールを直接使用できます。

# List recent HTTP requests
@laravel-telescope-mcp requests --limit 5

# Details of a specific exception
@laravel-telescope-mcp exceptions --id 123456

# Find slow queries
@laravel-telescope-mcp queries --slow true --limit 10

使用例

MCP ツールの直接使用（推奨）

接続後は、AI アシスタントで MCP ツールを直接使用できます。

# List recent HTTP requests
@laravel-telescope-mcp requests --limit 5

# Get details of a specific exception
@laravel-telescope-mcp exceptions --id 123456

# Find slow database queries
@laravel-telescope-mcp queries --slow true --limit 10

# Check recent logs
@laravel-telescope-mcp logs --level error --limit 5

自然言語での問い合わせ

• 「アプリケーションの直近 5 件のエラーログを表示してください」
• 「100ms を超える SQL クエリを特定してください」
• 「直近 1 時間に失敗したジョブをすべて表示してください」
• 「ステータスコードが 5xx の HTTP リクエストを要約してください」

AI は適切な MCP ツールを自動的に使用して、データを取得・分析します。

利用可能なツール

19 個の MCP ツールはすべて完全に稼働しており、人間が読みやすいテキストと JSON データの両方を含む構造化された応答を提供します。

ツール	状態	説明	主なパラメーター
Requests	✅	受信した HTTP リクエストを記録します	id、limit、method、status、path
Exceptions	✅	スタックトレースとともにアプリケーションエラーを追跡します	id、limit
Queries	✅	パフォーマンス指標を含めてデータベースクエリを監視します	id、limit、slow（ブール値）
Logs	✅	フィルタリング機能を備えてアプリケーションログを記録します	id、limit、level、message
HTTP Client	✅	送信 HTTP リクエストを監視します	id、limit、method、status、url
Mail	✅	メール操作を監視します	id、limit、to、subject
Notifications	✅	通知の送信を記録します	id、limit、channel、status
Jobs	✅	キューに登録されたジョブの実行を追跡します	id、limit、status、queue
Events	✅	イベントの送信を監視します	id、limit、name
Models	✅	Eloquent モデルの操作を追跡します	id、limit、action、model
Cache	✅	キャッシュ操作を監視します	id、limit、operation、key
Redis	✅	Redis 操作を追跡します	id、limit、command
Schedule	✅	スケジュールされたタスクの実行を監視します	id、limit
Views	✅	ビューのレンダリングを記録します	id、limit
Dumps	✅	var_dump と dd() の呼び出しを記録します	id、limit、file、line
Commands	✅	Artisan コマンドの実行を追跡します	id、limit、command、status
Gates	✅	認可チェックを記録します	id、limit、ability、result
Batches	✅	バッチ操作の一覧表示と分析を行います	id、limit、status、name
Prune	✅	古い Telescope エントリーを削除します	hours

現在の状況と機能

✅ MCP 統合の状況

• 19 個の MCP ツールが稼働中：Telescope の主要機能すべてに MCP 経由でアクセスできます
• Cursor とのネイティブ統合：外部コマンドを使わずに、Cursor 内でツールを直接利用できます
• 構造化された応答：各ツールは、人間が読みやすいテキストと JSON データの両方を返します
• リアルタイムのデータアクセス：HTTP リクエストを介さず、Telescope のテレメトリーに直接アクセスできます

🚀 主なメリット

• cURL はもう不要：AI アシスタントで MCP ツールを直接利用できます
• すぐに得られる分析情報：自然言語でアプリケーションの指標を取得できます
• 構造化データ：読みやすい要約とプログラムからのアクセスの両方に対応します
• Telescope の機能を網羅：主要な監視機能すべてにアクセスできます

📊 応答形式

各 MCP ツールが提供する内容：

• 人間が読みやすい出力：書式設定されたテーブルと要約
• JSON データ：プログラムによる処理に使える構造化データ
• MCP 準拠：標準の MCP 応答形式

🔧 ツールの機能

• 一覧操作：カスタマイズ可能な上限で概要を取得します
• 詳細表示：ID を指定して特定のエントリーを詳しく確認します
• フィルタリング：ステータス、レベル、時間範囲などのフィルターを適用します
• パフォーマンス指標：遅いクエリ、失敗したジョブ、エラーを追跡します

設定

• 認証：組み込みのベアラー認証を TELESCOPE_MCP_AUTH_ENABLED=true と MCP_BEARER_TOKEN（または TELESCOPE_MCP_BEARER_TOKEN）で使用するか、Laravel ミドルウェア（auth:sanctum、auth.basic）で保護します。
• エンドポイントパス：TELESCOPE_MCP_PATH をカスタマイズするか、config/telescope-mcp.php で変更します。
• ミドルウェア：TELESCOPE_MCP_MIDDLEWARE をカンマ区切りのリストとして設定します（例：api,auth:sanctum）。
• ロギング：内部 MCP ロギングを有効または無効にします。
• タイムアウトと上限：必要に応じて、リクエストのタイムアウトとペイロードの上限を調整します。

詳細設定

以下については config/telescope-mcp.php を参照してください。

• カスタムミドルウェアスタック
• 操作ごとの設定
• ルートと名前空間の上書き

パフォーマンスと監視

リアルタイムインサイト

• HTTP リクエスト：受信トラフィック、応答時間、ステータスコードを監視します
• データベースクエリ：遅いクエリを追跡し、パフォーマンスを最適化します
• アプリケーションエラー：詳細なスタックトレースとエラーのコンテキストを取得します
• ジョブ処理：キューのパフォーマンスと失敗を監視します
• キャッシュ操作：キャッシュのヒット率／ミス率とパフォーマンスを追跡します

データ保持

• 設定可能な上限：ニーズに応じて、各ツールに適切な上限を設定できます
• 効率的なクエリ：ツールは最適化された Telescope クエリを使用し、応答を高速化します
• メモリ管理：MCP クライアント向けに、応答を効率的にフォーマットします

コントリビューション

コントリビューションを歓迎します。CONTRIBUTING.md のガイドラインに従って、イシューまたはプルリクエストを送信してください。

ライセンス

MIT ライセンスの下でライセンスされています。詳細は LICENSE を参照してください。