What is Telescopemcp

The Laravel Telescope MCP Server is a Model Context Protocol server that facilitates AI agents’ access to Laravel Telescope data, enabling advanced debugging and analysis of Laravel applications. It allows developers to query and analyze application performance data without relying on the traditional web UI.

Use cases

The MCP server can be used for various debugging scenarios, such as identifying slow response times, recognizing N+1 query issues and memory leaks, filtering requests by specific criteria, and summarizing failed API requests. It supports natural language queries, making it easier for developers to diagnose issues quickly.

How to use

To use the MCP server, you need to install the ‘uv’ package, clone the repository, and set up your AI assistant. This process involves configuring a connection to the Laravel Telescope data and specifying your database credentials and project paths using environment variables. Once configured, you can interact with the server to analyze requests and debug performance issues.

Key features

Key features include natural language debugging for ease of use, instant pattern recognition capabilities, direct database access to Laravel Telescope data, advanced search options for filtering requests, AI-optimized output for data analysis, and seamless integration with Laravel Sail.

Where to use

This MCP server is particularly useful in software development environments where Laravel applications are deployed. It is ideal for developers and teams looking for efficient debugging tools, as well as for enhancing the performance of Laravel applications by addressing issues found during analysis.

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 [email protected]: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:[email protected]: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

1. Open Claude → Settings → Developer → Edit Config.
2. 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).

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

1. requests(page=1, search=None): List recent HTTP requests.
2. search_requests(…): Advanced search with filters (controller, status, min_duration_ms, method, uri_pattern).
3. get_request(batch_id): Get an overview of a specific request.
4. get_request_queries(batch_id, page=1): Get SQL queries for a request.
5. get_request_models(batch_id, page=1): Get model operations for a request.
6. get_request_jobs(batch_id, page=1): Get jobs for a request.
7. get_request_views(batch_id, page=1): Get view data for a request.
8. get_request_cache(batch_id, page=1): Get cache events for a request.
9. get_request_redis(batch_id, page=1): Get Redis commands for a request.
10. get_request_notifications(batch_id, page=1): Get notifications for a request.
11. get_request_timing(batch_id): Get timing breakdown from Laravel Debugbar.
12. get_request_response(batch_id): Get the full response data.
13. get_request_payload(batch_id): Get the request payload (form data or JSON body).
14. 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:[email protected]: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:

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:[email protected]: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