PHPackages                             lucianotonet/laravel-telescope-mcp - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. lucianotonet/laravel-telescope-mcp

ActiveLibrary[Logging & Monitoring](/categories/logging)

lucianotonet/laravel-telescope-mcp
==================================

MCP Server extension for Laravel Telescope

v1.0.0(3mo ago)198.6k—4.5%3[2 PRs](https://github.com/lucianotonet/laravel-telescope-mcp/pulls)MITPHPPHP ^8.3CI passing

Since May 17Pushed 1mo ago2 watchersCompare

[ Source](https://github.com/lucianotonet/laravel-telescope-mcp)[ Packagist](https://packagist.org/packages/lucianotonet/laravel-telescope-mcp)[ RSS](/packages/lucianotonet-laravel-telescope-mcp/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (7)Versions (15)Used By (0)

[![Logo Laravel Telescope MCP](./art/logo.svg)](./art/logo.svg)

 [![Latest Version on Packagist](https://camo.githubusercontent.com/739ba74f2e775f9a460c936f8ce5ac4012a8099d1a949c8a816b48f2613f9718/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6c756369616e6f746f6e65742f6c61726176656c2d74656c6573636f70652d6d63702e737667)](https://packagist.org/packages/lucianotonet/laravel-telescope-mcp) [![Downloads](https://camo.githubusercontent.com/b219b90bb3f70ec9bedb62a16bf6d3abb4fce143986dcc2eca8bd5ea9fa47be0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6c756369616e6f746f6e65742f6c61726176656c2d74656c6573636f70652d6d63702e737667)](https://packagist.org/packages/lucianotonet/laravel-telescope-mcp) [![Tests](https://github.com/lucianotonet/laravel-telescope-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/lucianotonet/laravel-telescope-mcp/actions/workflows/tests.yml) [![License](https://camo.githubusercontent.com/6813f6608432afd99bb2d34d939ff4ae264b50f65939bb6e4a7b414b196d8f1b/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6c756369616e6f746f6e65742f6c61726176656c2d74656c6573636f70652d6d6370)](LICENSE)

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
--------

[](#overview)

Telescope MCP exposes all Laravel Telescope telemetry data via the Model Context Protocol (MCP), enabling AI assistants to directly access and analyze application metrics. This provides developers with instant insights into logs, slow queries, HTTP requests, exceptions, jobs, and more through natural language queries.

Requirements
------------

[](#requirements)

- PHP 8.3+
- Laravel 11 or 12
- Laravel Telescope 5.0+

Important

The HTTP MCP endpoint is **not authenticated by default**. If you expose it online, enable authentication first (see "Secure Streamable HTTP in IDEs").

**Status**: ✅ **19 MCP tools fully operational and integrated**

### What's New in v1.0

[](#whats-new-in-v10)

🎉 **Now powered by the official [Laravel/MCP](https://github.com/laravel/mcp) package!**

- Built on Laravel's official MCP framework for better maintainability and long-term support
- Improved architecture with cleaner tool definitions using `Laravel\Mcp\Server\Tool`
- Enhanced schema validation with `JsonSchema` builder
- Better request handling with `Laravel\Mcp\Request` and `Laravel\Mcp\Response`
- Full backward compatibility maintained - all 19 tools work identically
- Ready for future Laravel/MCP features (Resources, Prompts, OAuth authentication)

Quick Start
-----------

[](#quick-start)

1. **Install the package:**

    ```
    composer require lucianotonet/laravel-telescope-mcp --dev
    ```
2. **Auto-configure your MCP client:**

    ```
    php artisan telescope-mcp:install
    ```

    > 💡 Automatically detects and configures: **Cursor**, **Claude Code**, **Windsurf**, **Cline**, **Gemini App**, **Antigravity**, **Codex**, and **OpenCode**.
3. **Restart your IDE/editor** and start using tools!

---

Detailed Installation
---------------------

[](#detailed-installation)

### 1. Require Package

[](#1-require-package)

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

### 2. Configure MCP Client

[](#2-configure-mcp-client)

You can use the automatic installer or configure manually.

**Option A: Automatic Installation (Recommended)**

```
php artisan telescope-mcp:install
```

This command will:

- Detect installed MCP clients
- Generate the correct configuration file (`mcp.json`, `settings.json`, etc.)
- Set up the server in `stdio` mode

**Option B: Manual Configuration**Add the following to your MCP client's configuration file:

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

Important

**Antigravity users:** Antigravity does not support the `cwd` property. You must use the absolute path to `artisan` in the `args` array and it is recommended to add `"MCP_MODE": "stdio"` to the `env` object.

### 3. Verify Installation

[](#3-verify-installation)

Run the server manually to ensure it's working:

```
php artisan telescope-mcp:server
```

It should run silently (logging to stderr) and wait for JSON-RPC input.

---

Manual Configuration per Assistant
----------------------------------

[](#manual-configuration-per-assistant)

If you prefer to configure manually, add the following to your assistant's configuration file:

### Cursor, Windsurf, Cline

[](#cursor-windsurf-cline)

**File:** `mcp.json` or `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-code-cli)

You can configure via the `~/.claude/mcp.json` file (same format as Cursor) or via command:

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

### Antigravity

[](#antigravity)

**File:** `mcp_config.json` (Global configuration only)

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

### OpenCode

[](#opencode)

OpenCode uses a different key and requires the absolute path to `artisan`.

**File:** `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)

[](#codex-toml)

**File:** `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"
```

Troubleshooting (Stdio)
-----------------------

[](#troubleshooting-stdio)

### PHP or Artisan not found

[](#php-or-artisan-not-found)

Ensure `php` is in your global PATH or use the absolute path to the PHP executable. On Windows, use double backslashes `\\` in JSON/TOML paths.

### Permissions

[](#permissions)

Ensure the AI assistant has permission to read/write in your Laravel project's `storage` directory, where Telescope stores the data.

### MCP Logs

[](#mcp-logs)

If tools don't appear, check your assistant's error logs (e.g., Cursor Output > MCP). The command `php artisan telescope-mcp:server` should run without errors if executed manually in the terminal.

Using MCP Inspector (Browser UI / HTTP)
---------------------------------------

[](#using-mcp-inspector-browser-ui--http)

If you want to test your server from the browser using `@modelcontextprotocol/inspector`, use HTTP transport with your MCP endpoint URL.

### 1. Start Inspector against a remote/public endpoint

[](#1-start-inspector-against-a-remotepublic-endpoint)

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

### 2. Start Inspector against a local HTTPS endpoint

[](#2-start-inspector-against-a-local-https-endpoint)

If your local certificate is self-signed (common with `*.test` domains), disable TLS verification for Node in your current shell:

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

### 3. If default inspector ports are busy

[](#3-if-default-inspector-ports-are-busy)

Inspector uses ports `6274` (UI) and `6277` (proxy) by default. If you get "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. Optional auth headers

[](#4-optional-auth-headers)

If your MCP route is protected by middleware, pass headers:

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

### 5. Quick health check

[](#5-quick-health-check)

- `GET /telescope-mcp` returning `405` is expected.
- Use `POST /telescope-mcp` for MCP JSON-RPC requests.

Secure Streamable HTTP in IDEs
------------------------------

[](#secure-streamable-http-in-ides)

This package now supports built-in bearer token authentication for the HTTP MCP endpoint.

### 1. Enable auth in Laravel (`.env`)

[](#1-enable-auth-in-laravel-env)

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

You can also use `TELESCOPE_MCP_BEARER_TOKEN` instead of `MCP_BEARER_TOKEN`. Auth is automatically enabled when one of these token env vars is present. If you prefer explicit control, set:

```
TELESCOPE_MCP_AUTH_ENABLED=true
```

Generate a token example:

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

### 2. IDE UI mapping (Streamable HTTP)

[](#2-ide-ui-mapping-streamable-http)

For IDEs that ask fields like:

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

Use:

- `Name`: `laravel-telescope-online` (or any name)
- `Transport`: `Streamable HTTP`
- `URL`: `https://your-domain.com/telescope-mcp`
- `Bearer token env var`: `MCP_BEARER_TOKEN`

If your IDE does not support "Bearer token env var", set headers manually:

- `Key`: `Authorization`
- `Value`: `Bearer `

If your IDE supports "headers from env variables", prefer:

- `Key`: `Authorization`
- `Value`: `Bearer ${MCP_BEARER_TOKEN}`

### 3. Local and online examples

[](#3-local-and-online-examples)

- Local URL: `https://your-local-domain.test/telescope-mcp`
- Online URL: `https://your-public-domain.com/telescope-mcp`

Reference: OpenAI Codex MCP docs (`https://developers.openai.com/codex/mcp/`).

How to Use
----------

[](#how-to-use)

Once connected, you can use the MCP tools directly in your AI assistant:

```
# 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
```

Usage Examples
--------------

[](#usage-examples)

### Direct MCP Tool Usage (Recommended)

[](#direct-mcp-tool-usage-recommended)

Once connected, you can use the MCP tools directly in your AI assistant:

```
# 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
```

### Natural Language Queries

[](#natural-language-queries)

- *"Show me the last 5 error logs from the application"*
- *"Identify SQL queries taking longer than 100ms"*
- *"Display all failed jobs from the last hour"*
- *"Summarize HTTP requests with 5xx status codes"*

The AI will automatically use the appropriate MCP tools to fetch and analyze the data.

Available Tools
---------------

[](#available-tools)

All 19 MCP tools are fully operational and provide structured responses with both human-readable text and JSON data.

ToolStatusDescriptionKey Parameters**Requests**✅Records incoming HTTP requests`id`, `limit`, `method`, `status`, `path`**Exceptions**✅Tracks application errors with stack traces`id`, `limit`**Queries**✅Monitors database queries with performance metrics`id`, `limit`, `slow` (boolean)**Logs**✅Records application logs with filtering`id`, `limit`, `level`, `message`**HTTP Client**✅Monitors outgoing HTTP requests`id`, `limit`, `method`, `status`, `url`**Mail**✅Monitors email operations`id`, `limit`, `to`, `subject`**Notifications**✅Records notification dispatches`id`, `limit`, `channel`, `status`**Jobs**✅Tracks queued job executions`id`, `limit`, `status`, `queue`**Events**✅Monitors event dispatches`id`, `limit`, `name`**Models**✅Tracks Eloquent model operations`id`, `limit`, `action`, `model`**Cache**✅Monitors cache operations`id`, `limit`, `operation`, `key`**Redis**✅Tracks Redis operations`id`, `limit`, `command`**Schedule**✅Monitors scheduled task executions`id`, `limit`**Views**✅Records view renders`id`, `limit`**Dumps**✅Records var\_dump and dd() calls`id`, `limit`, `file`, `line`**Commands**✅Tracks Artisan command executions`id`, `limit`, `command`, `status`**Gates**✅Records authorization checks`id`, `limit`, `ability`, `result`**Batches**✅Lists and analyzes batch operations`id`, `limit`, `status`, `name`**Prune**✅Removes old Telescope entries`hours`Current Status & Features
-----------------------------

[](#current-status--features)

### ✅ **MCP Integration Status**

[](#-mcp-integration-status)

- **19 MCP tools operational**: All major Telescope features are now accessible via MCP
- **Native Cursor integration**: Tools work directly within Cursor without external commands
- **Structured responses**: Each tool returns both human-readable text and JSON data
- **Real-time data access**: Direct access to Telescope telemetry without HTTP requests

### 🚀 **Key Benefits**

[](#-key-benefits)

- **No more cURL needed**: Use MCP tools directly in your AI assistant
- **Instant insights**: Get application metrics through natural language
- **Structured data**: Both readable summaries and programmatic access
- **Full Telescope coverage**: Access to all major monitoring features

### 📊 **Response Format**

[](#-response-format)

Each MCP tool provides:

- **Human-readable output**: Formatted tables and summaries
- **JSON data**: Structured data for programmatic processing
- **MCP compliance**: Standard MCP response format

### 🔧 **Tool Capabilities**

[](#-tool-capabilities)

- **List operations**: Get overviews with customizable limits
- **Detail views**: Drill down into specific entries by ID
- **Filtering**: Apply filters like status, level, time ranges
- **Performance metrics**: Track slow queries, failed jobs, errors

Configuration
-------------

[](#configuration)

- **Authentication**: Use built-in bearer auth with `TELESCOPE_MCP_AUTH_ENABLED=true` and `MCP_BEARER_TOKEN` (or `TELESCOPE_MCP_BEARER_TOKEN`), or protect with Laravel middleware (`auth:sanctum`, `auth.basic`).
- **Endpoint Path**: Customize `TELESCOPE_MCP_PATH` or modify in `config/telescope-mcp.php`.
- **Middleware**: Set `TELESCOPE_MCP_MIDDLEWARE` as comma-separated list (e.g., `api,auth:sanctum`).
- **Logging**: Enable or disable internal MCP logging.
- **Timeouts & Limits**: Adjust request timeouts and payload limits as needed.

Advanced
--------

[](#advanced)

See `config/telescope-mcp.php` for:

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

Performance & Monitoring
----------------------------

[](#performance--monitoring)

### **Real-time Insights**

[](#real-time-insights)

- **HTTP Requests**: Monitor incoming traffic, response times, and status codes
- **Database Queries**: Track slow queries and optimize performance
- **Application Errors**: Get detailed stack traces and error context
- **Job Processing**: Monitor queue performance and failures
- **Cache Operations**: Track cache hit/miss ratios and performance

### **Data Retention**

[](#data-retention)

- **Configurable limits**: Set appropriate limits for each tool based on your needs
- **Efficient queries**: Tools use optimized Telescope queries for fast responses
- **Memory management**: Responses are formatted efficiently for MCP clients

Contributing
------------

[](#contributing)

Contributions are welcome. Please submit issues or pull requests following our [CONTRIBUTING.md](/CONTRIBUTING.md) guidelines.

License
-------

[](#license)

Licensed under MIT. See [LICENSE](LICENSE) for details.

###  Health Score

52

—

FairBetter than 96% of packages

Maintenance85

Actively maintained with recent releases

Popularity36

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity59

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 97.6% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~87 days

Total

4

Last Release

103d ago

Major Versions

v0.3.0 → v1.0.02026-02-04

PHP version history (2 changes)v0.1.0PHP ^8.1

v1.0.0PHP ^8.3

### Community

Maintainers

![](https://www.gravatar.com/avatar/ea8cc36e3a5075029a70b8a2232e71035977e68319b2715790ec254520cf9ce9?d=identicon)[lucianotonet](/maintainers/lucianotonet)

---

Top Contributors

[![lucianotonet](https://avatars.githubusercontent.com/u/2693019?v=4)](https://github.com/lucianotonet "lucianotonet (81 commits)")[![greghunt](https://avatars.githubusercontent.com/u/1238407?v=4)](https://github.com/greghunt "greghunt (2 commits)")

---

Tags

laravelmonitoringmcpdebuggingcursordeveloper-toolstelescope

###  Code Quality

TestsPest

Code StylePHP CS Fixer

### Embed Badge

![Health badge](/badges/lucianotonet-laravel-telescope-mcp/health.svg)

```
[![Health](https://phpackages.com/badges/lucianotonet-laravel-telescope-mcp/health.svg)](https://phpackages.com/packages/lucianotonet-laravel-telescope-mcp)
```

###  Alternatives

[binarybuilds/laravel-mail-manager

A Laravel mail manager to record and re-send all outgoing emails.

2440.2k1](/packages/binarybuilds-laravel-mail-manager)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)