Laravel Artisan MCP 服务器

这是一个模型上下文协议（MCP）服务器，它通过 Claude 和其他 MCP 客户端实现 Laravel Artisan 命令的安全执行。该服务器充当 AI 助手与您的本地Laravel 应用程序之间的桥梁，允许通过自然语言对话来控制管理 Laravel 项目。

特性

• 访问包含 Laravel 项目的单个目录
• 自动在系统中定位 PHP
• 只执行白名单中的 Artisan 命令
• 查看所有可用的 Artisan 命令
• 设计上具有强大的输入验证，确保安全性

示例

要求

• Python 3.10 或更高版本
• 包含 Artisan CLI 的 Laravel 项目
• 已安装并可在 PATH 中访问的 PHP
• 兼容 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  # 在 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 之前测试您的服务器：

# 使用直接的环境变量运行
ARTISAN_DIRECTORY="/absolute/path/to/your/laravel/project" WHITELISTED_COMMANDS="route:list,cache:clear,make:controller" uv run mcp dev artisan_mcp_server.py

# 或使用 env 文件
uv run mcp dev artisan_mcp_server.py --env-file .env

一旦 Inspector 运行起来：

1. 在 http://localhost:5173 打开 Web 界面
2. 在“资源”标签页下查看可用资源
3. 在“工具”标签页下测试工具：
   • 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 必须在配置中提供"

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

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

"未在 /path/to/artisan 找到 Artisan"

指定的目录不包含 Artisan 可执行文件。验证：

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

"未找到 PHP 可执行文件"

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

• 您的系统上已安装 PHP
• PHP 可执行文件在您的系统 PATH 中

免责声明

本 Laravel Artisan MCP 服务器按原样提供，没有任何形式的担保或保证。使用此软件时，您承担与其操作相关的所有风险。该服务器有权在其 Laravel 环境中执行命令，这可能会对您的应用程序数据和功能产生潜在影响。我们强烈建议仅在开发或测试环境中使用此工具。仅当您完全理解安全影响并已实施适当的防护措施时，才应在生产 Laravel 应用程序中使用此服务器。在允许 AI 助手通过此接口执行 Artisan 命令之前，请始终维护您的 Laravel 项目的适当备份。本软件的作者和贡献者不对因使用或误用此工具而导致的任何损害、数据丢失或安全漏洞负责。您独自负责配置适当的命令白名单和访问控制。此软件未经正式安全审计，应被视为实验性的。自行承担风险使用。

许可证

本项目根据 MIT 许可证发布 - 详情请参阅 LICENSE 文件。

作者

此 MCP 服务器是在 Claude（Anthropic 的 AI 助手）的帮助下制作的（他坚持添加这个谦虚的致谢，同时承诺不会包含笑脸表情符号或过度的热情）。