Laravel Artisan MCP

🚀 Laravel Artisan MCP Server

A Model Context Protocol (MCP) server that allows secure execution of Laravel Artisan commands via Claude and other MCP clients. This server acts as a bridge between the AI assistant and your local Laravel application, enabling controlled management of Laravel projects through natural language conversations.

✨ Features

• Access a single directory containing a Laravel project.
• Automatically locate PHP in the system.
• Execute only whitelisted Artisan commands.
• View all available Artisan commands.
• Designed with security in mind, featuring robust input validation.

🖼️ Examples

📋 Requirements

• Python 3.10 or higher.
• A Laravel project with the Artisan CLI.
• PHP installed and accessible in the PATH.
• An MCP-compatible client (e.g., Claude Desktop).

📦 Installation

1. Clone the repository:

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

2. Create a virtual environment and install dependencies:

   python -m venv venv
   source venv/bin/activate  # Use `venv\Scripts\activate` on Windows
   pip install -r requirements.txt
   

3. Run the server:

   python server.py
   

⚙️ Configuration

Edit the configuration file config.py and set the following parameters:

• ARTISAN_DIRECTORY: Specify your Laravel project directory.
• COMMAND_WHITELIST: List the allowed commands.

💻 Usage Examples

Basic Usage

# Execute an Artisan command
python server.py --command "php artisan migrate"

# Display help information
python server.py --help

⚠️ Security Considerations

• Directory Isolation: Only access the specified Laravel directory.
• Command Whitelisting: Execute only specifically allowed commands.
• Input Validation: Validate all inputs before execution.
• Error Handling: Prevent the leakage of sensitive information.

🛠️ Troubleshooting

"ARTISAN_DIRECTORY must be provided in the configuration"

The server cannot find your Laravel project path. Check the following:

• Whether the environment variables are set correctly.
• Whether the directory exists and is accessible.

"Artisan not found in /path/to/artisan"

The specified directory does not contain the Artisan executable. Verify the following:

• Whether the path points to a valid Laravel project directory.
• Whether the Artisan file exists and has executable permissions.

"PHP executable not found"

The server cannot find PHP in the PATH. Ensure the following:

• PHP is installed.
• The PHP executable is in the system PATH.

📄 Disclaimer

This Laravel Artisan MCP server is provided as-is, without any form of warranty or guarantee. By using this software, you agree to assume all risks associated with its operation. This server can execute commands in a development or testing environment, which may affect your application data and functionality. We strongly recommend using this tool in a production Laravel application only after understanding its security implications and implementing appropriate safeguards. Always back up your Laravel project before allowing an AI assistant to execute Artisan commands through this interface. This software has not undergone a formal security audit and should be considered experimental. Use at your own risk.

📄 License

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

👨‍💻 Author

This MCP server was developed with the assistance of Claude (Anthropic's AI assistant), who insisted on adding this humble note of thanks while promising to avoid emojis or excessive enthusiasm.