laravel-artisan-mcp | 通往MCP之路

Laravel Artisan MCP Server

一个基于模型上下文协议（Model Context Protocol, MCP）的服务器，支持通过 Claude 和其他 MCP 客户端安全地执行 Laravel Artisan 命令。该服务器充当 AI 助手与本地 Laravel 应用程序之间的桥梁，允许通过自然语言对话对 Laravel 项目进行受控管理。

功能特性

自动定位系统中的 PHP 可执行文件

仅执行白名单中的 Artisan 命令

查看所有可用的 Artisan 命令

设计安全，具备强大的输入验证机制

示例

系统要求

Python 3.10 或更高版本

包含 Artisan CLI 的 Laravel 项目

已安装 PHP 并可在系统 PATH 中访问

兼容 MCP 的客户端（如 Claude Desktop）

安装步骤

克隆本仓库：

创建虚拟环境：

安装依赖：

配置

服务器需要以下环境变量：

ARTISAN_DIRECTORY：包含 Artisan 可执行文件的 Laravel 项目的绝对路径

WHITELISTED_COMMANDS：允许执行的 Artisan 命令列表，以逗号分隔（例如：route:list,cache:clear,make:controller 或 Laravel 应用中注册的任何默认或自定义命令）

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

直接在命令行中设置：

使用 .env 文件：

在 Claude Desktop 配置中设置（详见下方 Claude 集成部分）

使用 MCP Inspector 测试

MCP Inspector 提供了一个图形界面，用于在集成到 Claude 之前测试服务器：

运行 Inspector 后：

打开 http://localhost:5173 访问 Web 界面

在 "Resources" 选项卡中查看可用资源

在 "Tools" 选项卡中测试工具：

list_available_artisan_commands：显示 Laravel 项目中所有白名单命令

run_artisan：执行特定命令（必须为白名单中的命令）

Claude 集成

将服务器与 Claude Desktop 集成的步骤：

确保已安装 Claude Desktop

编辑 Claude Desktop 配置文件：

macOS：

Windows：

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

重启 Claude Desktop

可用工具

`run_artisan`

执行白名单中的 Artisan 命令。

参数：

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

在 Claude 中的使用示例： "Run the route:list command to show all available routes in my Laravel app."

`list_available_artisan_commands`

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

在 Claude 中的使用示例： "Show me all available Artisan commands."

安全考虑

该服务器实现了多项安全措施（根据 Claude 的建议）：

目录隔离：仅访问明确配置的 Laravel 目录

命令白名单：仅执行明确允许的命令

输入验证：在执行前验证所有输入

错误处理：防止敏感信息泄露

故障排除

"ARTISAN_DIRECTORY must be provided in configuration"

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

是否正确设置了环境变量

"Artisan not found at: /path/to/artisan"

指定目录中未找到 Artisan 可执行文件。请确认：

Artisan 文件存在且具有可执行权限

"PHP executable not found"

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

系统中已安装 PHP

PHP 可执行文件在系统 PATH 中

免责声明

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

许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件。

作者

本 MCP 服务器在 Claude（Anthropic 的 AI 助手）的协助下完成（Claude 坚持要求添加此谦逊的致谢，并承诺不会使用表情符号或过度热情的表达）。