mcp-server-laravel

<div align="center"> <img src="demo.gif" width="720" alt="Laravel Codebase MCP Server Demo"> <br> <em>Browse routes, models, controllers, migrations via MCP</em> </div>

Laravel Codebase MCP Server — introspect routes, models, controllers, migrations, and more through the Model Context Protocol. Works with any AI client that supports MCP: opencode, Claude Desktop, Cursor, and others.

Stop grepping your Laravel codebase. Let your AI assistant answer "what routes exist?", "show me the User model", or "list all migrations" instantly.

---

Quick Start

# Install
npx mcp-server-laravel-codebase

# Or clone
git clone git@github.com:rendi-febrian/mcp-server-laravel-codebase.git
cd mcp-server-laravel-codebase
npm install && npm run build

opencode Configuration

Add to ~/.config/opencode/opencode.json:

{
  "mcp": {
    "laravel-codebase": {
      "type": "local",
      "command": ["node", "/path/to/mcp-server-laravel/dist/index.js"],
      "environment": {
        "LARAVEL_PROJECT_PATH": "/path/to/your/laravel-project"
      },
      "enabled": true
    }
  }
}

Claude Desktop / Cursor / Other MCP Clients

{
  "mcpServers": {
    "laravel-codebase": {
      "command": "node",
      "args": ["/path/to/mcp-server-laravel/dist/index.js"],
      "env": {
        "LARAVEL_PROJECT_PATH": "/path/to/your/laravel-project"
      }
    }
  }
}

Features

Tools

Tool	Description	Example
routes_list	All routes with method, URI, controller, middleware	routes_list(method: "GET")
models_list	All Eloquent models with paths and namespaces	models_list()
model_detail	Single model: columns, relations, casts, policies	model_detail(name: "User")
controllers_list	Controllers with optional route mapping	controllers_list(detail: true)
app_about	Laravel version, env, packages, config	app_about()
migrations_list	Migration status (ran/pending)	migrations_list()
schedule_list	Scheduled tasks with frequency	schedule_list()
events_list	Events and registered listeners	events_list()
middleware_list	Middleware aliases with class names	middleware_list()
commands_list	All registered Artisan commands	commands_list(filter: "make")
artisan_run	Run read-only Artisan commands	artisan_run(command: "route:list --json")

Resources

URI	Content
laravel://about	Application info (version, env, drivers)
laravel://routes	Full route table as JSON

Security

artisan_run is restricted to read-only commands:

route:list · model:show · about · migrate:status · schedule:list · event:list · middleware · db:show · db:table · config:show · queue:failed · package:discover

Write operations (migrate, make:*, db:wipe, etc.) are blocked.

Requirements

• Node.js >= 18
• PHP 8.1+ with php on PATH
• A Laravel project (Laravel 9/10/11/12/13)

Environment Variables

Variable	Required	Default	Description
LARAVEL_PROJECT_PATH	Yes	—	Absolute path to Laravel project root
PHP_BINARY	No	php	Path to PHP binary

Switching Projects

Point LARAVEL_PROJECT_PATH at any Laravel project. No rebuild needed.

// Inspect FlightManagement API
"LARAVEL_PROJECT_PATH": "/home/user/Kerjaan/FlightManagement"

// Inspect admin panel
"LARAVEL_PROJECT_PATH": "/home/user/Projects/admin-panel"

Architecture

src/
├── index.ts              # MCP server entry point (raw Server)
├── artisan.ts            # PHP exec wrapper + whitelist
├── scanner.ts            # Laravel filesystem scanner
├── tools/
│   ├── routes.ts         # routes_list, routes_cache, routes_clear
│   ├── models.ts         # models_list, model_detail
│   ├── controllers.ts    # controllers_list
│   ├── migrations.ts     # migrations_list
│   ├── schedule.ts       # schedule_list
│   ├── events.ts         # events_list
│   ├── middleware.ts      # middleware_list
│   ├── about.ts          # app_about
│   ├── commands.ts       # commands_list
│   └── artisan.ts        # artisan_run
└── resources/
    └── index.ts          # laravel:// URIs

No external API calls — everything runs locally via php artisan commands and filesystem scanning.

Contributing

See CONTRIBUTING.md.

License

MIT