Laravel Telescope MCP

An extension for Laravel Telescope that exposes telemetry data via the Model Context Protocol (MCP) to AI assistants (e.g., Cursor, Claude, Copilot Chat). Ideal for developers who use Telescope to inspect application metrics and require quick, precise insights.

Overview

Telescope MCP translates natural-language queries into MCP operations, retrieves Telescope records, and returns concise responses. This enables developers to query logs, slow queries, HTTP requests, exceptions, jobs, and more using an AI interface.

Installation

Make sure you have Laravel Telescope properly installed and configured in your application before proceeding

1. Add the package via Composer:

   composer require lucianotonet/laravel-telescope-mcp
   

2. Publish the configuration (optional):

   php artisan vendor:publish --provider="LucianoTonet\TelescopeMcp\TelescopeMcpServiceProvider"
   

3. Update your .env (optional):

   TELESCOPE_MCP_ENABLED=true
   TELESCOPE_MCP_PATH=telescope-mcp
   

   You can now verify the installation by accessing http://localhost:8000/telescope-mcp/manifest.json in your browser

Connecting an AI Client

For Cursor (example):

1. Open Cursor command palette (Cmd/Ctrl+Shift+P).

2. Run View: Open MCP Settings.

3. Add this configuration:

   {
     "mcpServers": {
       "Laravel Telescope MCP": {
         "command": "npx",
         "args": [
           "-y", 
           "mcp-remote", 
           "http://localhost:8000/telescope-mcp",
           "--allow-http"
         ],
         "env": { "NODE_TLS_REJECT_UNAUTHORIZED": "0" }
       }
     }
   }
   

   Make sure the URL matches your .env configuration, combining APP_URL with TELESCOPE_MCP_PATH

4. For HTTPS, you can omit --allow-http and NODE_TLS_REJECT_UNAUTHORIZED like this:

   {
     "mcpServers": {
       "Laravel Telescope MCP": {
         "command": "npx",
         "args": [
           "-y", 
           "mcp-remote", 
           "https://example.com/telescope-mcp"            
         ]
       }
     }
   }
   

Usage Examples

• "Using your MCP tools, fetch the last 5 error logs."
• "Identify SQL queries longer than 100ms in the past twenty minutes."
• "Show all last failed jobs."
• "Summarize HTTP requests with status >=500 since last hour."

The AI will parse the query, call the MCP endpoint, analyze results, and return a summary.

Available Tools

Tool	Description	Parameters
Batches	Lists and analyzes batch operations	id, limit, status (pending/processing/finished/failed), name
Cache	Monitors cache operations	id, limit, operation (hit/miss/set/forget), key
Commands	Tracks Artisan command executions	id, limit, command, status (success/error)
Dumps	Records var_dump and dd() calls	id, limit, file, line
Events	Monitors event dispatches	id, limit, name
Exceptions	Tracks application errors	id, limit
Gates	Records authorization checks	id, limit, ability, result (allowed/denied)
HTTP Client	Monitors outgoing HTTP requests	id, limit, method, status, url
Jobs	Tracks queued job executions	id, limit, status (pending/processed/failed), queue
Logs	Records application logs	id, limit, level, message
Mail	Monitors email operations	id, limit, to, subject
Models	Tracks Eloquent model operations	id, limit, action (created/updated/deleted), model
Notifications	Records notification dispatches	id, limit, channel, status (sent/failed)
Queries	Monitors database queries	id, limit, slow (boolean)
Redis	Tracks Redis operations	id, limit, command
Requests	Records incoming HTTP requests	id, limit, method, status, path
Schedule	Monitors scheduled task executions	id, limit
Views	Records view renders	id, limit
Prune	Removes old Telescope entries	hours

Configuration

• Authentication: Protect the MCP endpoint using middleware (e.g., auth:sanctum, auth.basic).
• Endpoint Path: Customize TELESCOPE_MCP_PATH or modify in config/telescope-mcp.php.
• Logging: Enable or disable internal MCP logging.
• Timeouts & Limits: Adjust request timeouts and payload limits as needed.

Advanced

See config/telescope-mcp.php for:

• Custom middleware stacks
• Operation-specific settings
• Route and namespace overrides

Contributing

Contributions are welcome. Please submit issues or pull requests following our CONTRIBUTING.md guidelines.

License

Licensed under MIT. See LICENSE for details.