READMEmain

Laravel Telescope MCP Server

A Model Context Protocol (MCP) server that provides AI agents with direct access to Laravel Telescope data, enabling efficient debugging and analysis of Laravel applications.

Key Features

Natural Language Debugging: Ask "Why is the checkout page slow?" instead of clicking through Telescope.
Instant Pattern Recognition: AI can spot N+1 queries, memory leaks, and performance issues across thousands of requests.
Direct Database Access: Query Laravel Telescope data without the web UI.
Advanced Search: Filter requests by controller, status, duration, method, and URI.
AI-Optimized Output: Cleaned JSON data with numeric values for easy analysis.
Laravel Sail Ready: Works out of the box with Laravel Sail's default database.

Quick Start

Get up and running in 3 simple steps:

Step 1: Install `uv` (Python package manager)

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Step 2: Clone and install dependencies

git clone git@github.com:bradleybernard/TelescopeMCP.git
cd TelescopeMCP
uv sync

Step 3: Configure your AI assistant

Navigate to your Laravel project's root directory to perform this step, not the TelescopeMCP directory.

For Claude Code (Recommended)

Use the claude mcp command to connect the MCP server. This will create or update a .claude/mcp.json file in your Laravel project, telling your AI assistant how to communicate with the Telescope MCP server.

Run the following command after replacing the placeholder paths with the correct absolute paths for your system. This example uses database credentials for a default Laravel Sail setup.

# From your Laravel project root directory:
claude mcp add-json telescope '{
  "type": "stdio",
  "command": "/path/to/uv",
  "args": [
    "--directory",
    "/path/to/TelescopeMCP",
    "run",
    "python",
    "telescope_mcp_server.py"
  ],
  "env": {
    "DB_URL": "mysql+pymysql://sail:password@127.0.0.1:3306/laravel",
    "LARAVEL_PROJECT_PATH": "/path/to/laravel-project"
  }
}'

/path/to/uv: Replace with the absolute path to the uv executable. Find it by running which uv.
/path/to/TelescopeMCP: Replace with the absolute path to the TelescopeMCP directory you cloned in Step 2.
/path/to/laravel-project: Replace with the absolute path to your Laravel project root directory.

After running the command, restart Claude Code to apply the changes. Once you boot up claude you should be able to run /mcp to see telescope connected and ready to use.

To reconfigure (ie: change the database URL or Laravel project path), run claude mcp remove telescope first from your Laravel project directory, then re-run the claude mcp add-json telescope command above.

For Claude Desktop

Open Claude → Settings → Developer → Edit Config.
Add the telescope server to mcpServers. Replace placeholders with your actual paths and database URL.

{
  "mcpServers": {
    "telescope": {
      "type": "stdio",
      "command": "/path/to/uv",
      "args": [
        "--directory",
        "/path/to/TelescopeMCP",
        "run",
        "python",
        "telescope_mcp_server.py"
      ],
      "env": {
        "DB_URL": "mysql+pymysql://user:pass@host:port/db",
        "LARAVEL_PROJECT_PATH": "/path/to/your/laravel/project"
      }
    }
  }
}

Tip: Find your uv path with which uv (macOS/Linux) or where uv (Windows).

Restart Claude Desktop.

How It Works

Your Laravel App → Telescope → MySQL Database
                                    ↓
                              Telescope MCP
                                    ↓
                            AI Assistant
                                    ↓
                          Natural Language Debugging

The MCP server connects directly to your Laravel database and queries the telescope_entries table, providing your AI assistant with structured data optimized for debugging.

Usage Examples

Once configured, you can ask your AI assistant to interact with your Laravel Telescope data.

You: "Show me recent telescope requests."

AI: Analyzes recent requests, pointing out a 500 error on the /api/checkout endpoint that took over 3 seconds. Would you like to investigate?

You: "Why was that request so slow?"

AI: Identifies an N+1 query problem, suggesting an eager loading fix that could improve response time by over 50%. It also finds a query that could benefit from a new database index.

You: "Show me all failed API requests in the last hour."

AI: Lists failed requests, summarizing them by error type (validation, not found, authorization) and highlighting endpoints with recurring issues.

Available Tools

requests(page=1, search=None): List recent HTTP requests.
search_requests(...): Advanced search with filters (controller, status, min_duration_ms, method, uri_pattern).
get_request(batch_id): Get an overview of a specific request.
get_request_queries(batch_id, page=1): Get SQL queries for a request.
get_request_models(batch_id, page=1): Get model operations for a request.
get_request_jobs(batch_id, page=1): Get jobs for a request.
get_request_views(batch_id, page=1): Get view data for a request.
get_request_cache(batch_id, page=1): Get cache events for a request.
get_request_redis(batch_id, page=1): Get Redis commands for a request.
get_request_notifications(batch_id, page=1): Get notifications for a request.
get_request_timing(batch_id): Get timing breakdown from Laravel Debugbar.
get_request_response(batch_id): Get the full response data.
get_request_payload(batch_id): Get the request payload (form data or JSON body).
slow_queries(): Find all database queries exceeding a time threshold.

Configuration

The server is configured through environment variables passed in your MCP setup.

Database Connection

The recommended way to configure your database connection is with the DB_URL environment variable.

DB_URL="mysql+pymysql://username:password@host:port/database"

Example for Laravel Sail: DB_URL="mysql+pymysql://sail:password@127.0.0.1:3306/laravel"

Alternatively, you can set individual environment variables: DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD. If DB_URL is set, it takes precedence.

Laravel Project Path (for Debugbar)

To use the get_request_timing tool, you must provide the absolute path to your Laravel project root directory via the LARAVEL_PROJECT_PATH environment variable. The server uses this path to locate Laravel Debugbar's JSON storage files.

Example: LARAVEL_PROJECT_PATH="/Users/me/Code/my-laravel-app"

Add this to your env configuration in your MCP setup:

"env": {
  "DB_URL": "mysql+pymysql://sail:password@127.0.0.1:3306/laravel",
  "LARAVEL_PROJECT_PATH": "/path/to/your/laravel/project"
}

Development

Run locally: uv run python telescope_mcp_server.py
Test with inspector: uv run mcp dev telescope_mcp_server.py
Dependencies: See pyproject.toml.
Test with inspector (and DB_URL in ENV):

DB_URL="mysql+pymysql://sail:password@127.0.0.1:3306/laravel" uv run python telescope_mcp_server.py

Troubleshooting

Connection Errors: Ensure your database is running and accessible. Check your credentials and that the telescope_entries table exists.
No Data: Verify Telescope is enabled and recording data in your Laravel app (TELESCOPE_ENABLED=true).

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Built for Laravel Telescope
Uses the Model Context Protocol
Compatible with Claude Desktop and Claude Code

TelescopeMCP