Laravel Artisan MCP Server

Laravel Artisan MCP 服务

一个模型上下文协议（MCP）服务，可通过 Claude 和其他 MCP 客户端安全地执行 Laravel Artisan 命令。该服务充当 AI 助手与本地 Laravel 应用之间的桥梁，让你能够通过自然语言对话，以受控方式管理 Laravel 项目。

功能

• 访问包含 Laravel 项目的单个目录
• 自动查找系统上的 PHP
• 仅执行列入白名单的 Artisan 命令
• 查看所有可用的 Artisan 命令
• 采用安全设计，并进行完善的输入验证

示例

要求

• Python 3.10 或更高版本
• 带有 Artisan CLI 的 Laravel 项目
• 已安装 PHP，且可通过 PATH 访问
• 兼容 MCP 的客户端（例如 Claude Desktop）

安装

1. 克隆此仓库：

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

2. 创建虚拟环境：

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

3. 安装依赖项：

   uv add "mcp[cli]"
   

配置

服务需要以下环境变量：

• ARTISAN_DIRECTORY：包含 Artisan 可执行文件的 Laravel 项目的绝对路径
• WHITELISTED_COMMANDS：允许使用的 Artisan 命令列表，以逗号分隔（例如 route:list,cache:clear,make:controller，也可以是 Laravel 应用中注册的任何默认或自定义命令）

你可以通过以下几种方式提供这些变量：

1. 直接在命令行中：

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

2. 使用 .env 文件：

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

3. 在 Claude Desktop 配置中（参见下文的 Claude 集成部分）

使用 MCP Inspector 进行测试

MCP Inspector 提供了图形界面，可在将服务集成到 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

Inspector 运行后：

1. 在 http://localhost:5173 打开 Web 界面
2. 查看“Resources”选项卡，了解可用资源
3. 在“Tools”选项卡中测试工具：
   • list_available_artisan_commands：显示 Laravel 项目中所有列入白名单的命令
   • run_artisan：执行指定命令（必须列入白名单）

Claude 集成

要将此服务与 Claude Desktop 搭配使用：

1. 确保已安装 Claude Desktop

2. 编辑 Claude Desktop 配置文件：

   macOS：

   nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
   

   Windows：

   notepad %APPDATA%\Claude\claude_desktop_config.json
   

3. 添加以下配置（根据需要调整路径）：

   {
     "mcpServers": {
       "laravel-artisan": {
         "command": "uv",
         "args": [
           "--directory", 
           "/absolute/path/to/laravel-artisan-mcp",
           "run", 
           "artisan_mcp_server.py"
         ],
         "env": {
           "ARTISAN_DIRECTORY": "/absolute/path/to/your/laravel/project",
           "WHITELISTED_COMMANDS": "route:list,cache:clear,make:controller"
         }
       }
     }
   }
   

4. 重启 Claude Desktop

可用工具

run_artisan

执行列入白名单的 Artisan 命令。

参数：

• command：要运行的 Artisan 命令（例如 'cache:clear'）

在 Claude 中的使用示例： “运行 route:list 命令，显示我的 Laravel 应用中的所有可用路由。”

list_available_artisan_commands

显示 Laravel 应用中所有可用且列入白名单的 Artisan 命令。

在 Claude 中的使用示例： “显示所有可用的 Artisan 命令。”

安全注意事项

此服务实现了多项安全措施（依据 Claude）：

• 目录隔离：仅访问明确配置的 Laravel 目录
• 命令白名单：仅执行明确允许的命令
• 输入验证：执行前验证所有输入
• 错误处理：防止敏感信息泄露

故障排除

“ARTISAN_DIRECTORY must be provided in configuration”

服务无法找到 Laravel 项目的路径。请检查：

• 是否已正确设置环境变量
• 目录是否存在且可访问

“Artisan not found at: /path/to/artisan”

指定目录中不包含 Artisan 可执行文件。请确认：

• 路径指向有效的 Laravel 项目目录
• Artisan 文件存在且具有可执行权限

“PHP executable not found”

服务无法在 PATH 中找到 PHP。请确保：

• 系统上已安装 PHP
• PHP 可执行文件位于系统 PATH 中

免责声明

此 Laravel Artisan MCP 服务按“原样”提供，不提供任何形式的保证。使用本软件即表示您承担与其运行相关的所有风险。该服务可以在您的 Laravel 环境中执行命令，这可能会影响您的应用程序数据和功能。我们强烈建议仅在开发或测试环境中使用此工具。只有在您充分了解安全影响并已采取适当防护措施的情况下，才应将此服务用于生产环境中的 Laravel 应用程序。在允许 AI 助手通过此接口执行 Artisan 命令之前，请务必妥善备份您的 Laravel 项目。对于因使用或误用此工具而可能导致的任何损害、数据丢失或安全漏洞，本软件的作者和贡献者概不负责。您须自行负责配置适当的命令白名单和访问控制。本软件尚未经过正式的安全审计，应视为实验性软件。使用风险自负。

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

作者

此 MCP 服务是在 Claude（Anthropic 的 AI 助手）的协助下精心打造的（Claude 坚持要加上这段谦逊的致谢，同时承诺不会加入笑脸表情符号或过度热情的表达）。