Laravel Artisan MCP Server

A Model Context Protocol (MCP) server that enables secure execution of Laravel Artisan commands through Claude and other MCP clients. This server acts as a bridge between AI assistants and your local Laravel applications, allowing controlled management of Laravel projects through natural language conversations.

Features

• Access a single directory containing a Laravel project
• Automatically locate PHP on your system
• Execute only whitelisted Artisan commands
• View all available Artisan commands
• Secure by design with robust input validation

Examples

Requirements

• Python 3.10 or higher
• Laravel project with Artisan CLI
• PHP installed and accessible in your PATH
• MCP-compatible client (such as Claude Desktop)

Installation

1. Clone this repository:

   git clone https://github.com/diggy/laravel-artisan-mcp.git
   cd laravel-artisan-mcp
   

2. Create a virtual environment:

   uv init
   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. Install dependencies:

   uv add "mcp[cli]"
   

Configuration

The server requires the following environment variables:

• ARTISAN_DIRECTORY: Absolute path to the Laravel project containing the Artisan executable
• WHITELISTED_COMMANDS: Comma-separated list of allowed Artisan commands (e.g., route:list,cache:clear,make:controller or any default or custom Commands registered in your Laravel application)

You can provide these variables in several ways:

1. Directly in the command line:

   ARTISAN_DIRECTORY="/absolute/path/to/your/laravel/project" WHITELISTED_COMMANDS="route:list,cache:clear,make:controller" uv run artisan_mcp_server.py
   

2. Using a .env file:

   ARTISAN_DIRECTORY=/absolute/path/to/your/laravel/project
   WHITELISTED_COMMANDS=route:list,cache:clear,make:controller
   

3. In the Claude Desktop configuration (cf. section on Claude Integration below)

Testing with MCP Inspector

The MCP Inspector provides a graphical interface for testing your server before integrating it with Claude:

# Run with direct environment variables
ARTISAN_DIRECTORY="/absolute/path/to/your/laravel/project" WHITELISTED_COMMANDS="route:list,cache:clear,make:controller" uv run mcp dev artisan_mcp_server.py

# Or using an env file
uv run mcp dev artisan_mcp_server.py --env-file .env

Once the Inspector is running:

1. Open the web interface at http://localhost:5173
2. Explore the “Resources” tab to see available resources
3. Test the tools under the “Tools” tab:
   • list_available_artisan_commands: Shows all whitelisted commands in your Laravel project
   • run_artisan: Executes a specific command (must be whitelisted)

Claude Integration

To use this server with Claude Desktop:

1. Ensure Claude Desktop is installed