mateffy/laravel-codebase-mcp

An MCP server to give Cursor, Aider, etc. the ability to introspect your Laravel codebase directly, by querying for your models, views, routes and classes without raw file search.

0.0.2 2025-05-22 15:57 UTC

Requires

• php: ^8.2
• illuminate/contracts: ^10.0||^11.0||^12.0
• mateffy/laravel-introspect: ^1.1
• php-mcp/server: ^2.0.1
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• larastan/larastan: ^2.9||^3.0
• laravel/pint: ^1.14
• nunomaduro/collision: ^8.1.1||^7.10.0
• orchestra/testbench: ^10.0.0||^9.0.0||^8.22.0
• pestphp/pest: ^3.0
• pestphp/pest-plugin-arch: ^3.0
• pestphp/pest-plugin-laravel: ^3.0
• phpstan/extension-installer: ^1.3||^2.0
• phpstan/phpstan-deprecation-rules: ^1.1||^2.0
• phpstan/phpstan-phpunit: ^1.3||^2.0

MIT

• Lukas Mateffy

• laravel
• cursor
• ai
• mcp
• Lukas Mateffy
• laravel-codebase-mcp
• mcp-server

README

MCP Server for Laravel Codebase Intelligence and Introspection

For AIs to make sense of your codebase, they need to be able to know what's in it. While vector search is a powerful tool for searching through code, it uses a lot of tokens and doesn't even give you the full picture of your codebase for things like views or routes. This package implements a Model Context Protocol (MCP) server for the mateffy/laravel-introspect package, which allows you to introspect your codebase and get structured information about it.

• 🔍 Let AI query views, routes, classes and models without needing to read through all of the code
• 🔍 Can even use wildcards (*) to match multiple views, routes, classes and models
• 🔍 Supports querying for things from Laravel packages, which most file searchers can't do
• 🪄 Gives your AI quick overviews of your datamodel and its relationships
• 🤖 Supports any AI agent implementing the MCP protocol

Query	Available Filters
Views	name, path, used by view, uses view, extends
Routes	name, URI, controller + fn, methods, middleware
Classes	name / namespace, extends parent, implements interfaces, uses traits
⤷ Models	... relationships, properties, casts, fillable, hidden, read/writeable
⤷ Commands	... signature, description (coming soon)

Name and a few other queries even support wildcard queries (e.g. components.*.paragraph)

Who is this for?

If you use AI tools like Aider, Cursor, Windsurf or Claude Code to help you build your app, this package is for you. Simply configure the MCP server in your agent and it can automatically query your codebase for views, routes, classes and models.

This is especially useful for large codebases where just searching through the code is less practical.

Example tasks

• Give your AI an overview of your datamodel and its relationships
• Refactoring views and making sure it's not used anywhere else
• Finding all routes that use a specific controller
• Finding models that use a specific trait or interface
• Making sure all routes are using the correct middleware

laravel-codebase-mcp vs. laravel-introspect

The MCP server uses the laravel-introspect package to introspect your codebase and get structured information about it. If you want to write tests or run the same queries multiple times, you can also just use the package directly.

Installation

Install the package via composer:

composer require mateffy/laravel-codebase-mcp --dev

And then add it to your AI agent's MCP configuration:

{
  "mcpServers": {
    "laravel-introspect": {
      "command": "php",
      "args": [
        "/path/to/your/codebase/artisan",
        "introspect:mcp"
      ]
    }
  }
}

Note

The MCP server is still in beta, there will probably be bugs!

Available queries

If you want to see all available queries, please check the laravel-introspect package documentation.

Acknowledgements

The MCP server uses the php-mcp/server package to implement the MCP protocol.

License

The MIT License (MIT). Please see License File for more information.