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. 浏览 "Resources" 选项卡以查看可用资源
3. 在 "Tools" 选项卡下测试工具：
   • list_all_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_all_artisan_commands

显示 Laravel 应用程序中所有可用的 Artisan 命令。

在 Claude 中的示例用法： "向我展示我的 Laravel 项目中所有可用的 Artisan 命令。"

可用资源

artisan://commands

返回为服务器配置的所有白名单命令的列表。

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