cleaniquecoders/laravel-mcp-kit

A Laravel MCP starter kit: a task-management MCP server distilled from production patterns, with token and OAuth 2.1 auth.

1.2.0 2026-06-19 22:58 UTC

Requires

• php: ^8.4
• illuminate/contracts: ^11.0||^12.0||^13.0
• laravel/mcp: ^0.8.0
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/passport: ^13
• laravel/pint: ^1.14
• laravel/sanctum: ^4.0
• livewire/livewire: ^3.5
• nunomaduro/collision: ^8.8
• orchestra/testbench: ^11.0.0||^10.0.0||^9.0.0
• pestphp/pest: ^4.0
• pestphp/pest-plugin-arch: ^4.0
• pestphp/pest-plugin-laravel: ^4.0
• phpstan/extension-installer: ^1.4
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-phpunit: ^2.0

MIT

• Nasrul Hazim

• laravel
• mcp
• cleaniquecoders
• claude
• mcp-kit

README

A reusable starter package for adding a Model Context Protocol (MCP) server to your Laravel projects, built on the official laravel/mcp package. It ships a small task-management domain as a working reference and gives you, ready to copy or extend, the patterns a production MCP server needs.

Features

• Tools (read + write), Resources (read-by-URI context), and Prompts (reusable templates)
• A generic ops toolbox — whoami/abilities, system_health, logs (tail/search/export), failed-jobs + queue + scheduler, and — when the packages are present — audits, MCP token management, RBAC, and activity. See the catalogue.
• Opt-in by presence — Tier-2 tools auto-register only when their backing package (and table) exist
• Per-tool authorization via Gate abilities — MCP is a third UI, never a back door
• uuid-only inputs/outputs — the internal auto-increment id never leaks to the agent
• Write tools funnel through Action classes — the agent, web UI, and CLI share one rule set
• STDIO (local) and Streamable HTTP (remote) transports
• Two HTTP auth methods — Sanctum personal access tokens and OAuth 2.1 (Passport) — on one endpoint
• Honest annotations (#[IsReadOnly]) so clients know which tools change state and gate them
• A runtime on/off toggle, a mcp-kit:doctor wiring check, and gate-first generators (mcp-kit:make-tool / make-resource / make-prompt)

Preview

A publishable MCP settings & operations page (#16) — flip the runtime toggle and review system health, the effective config, mcp-kit:doctor results, and the live tool registry, all gated on manage-mcp. Publish it with php artisan mcp-kit:install --ui (Livewire + Flux), or preview it build-free in the workbench (composer serve → /mcp, see Workbench).

Requirements

• PHP 8.4+
• Laravel 11, 12, or 13
• laravel/mcp ^0.8

Installation

composer require cleaniquecoders/laravel-mcp-kit
php artisan mcp-kit:install   # publishes config + migration (add --oauth to wire OAuth 2.1)
php artisan migrate

Abilities

Every tool checks a Gate ability. The kit ships the ability names (in config('mcp-kit.abilities')); your app decides who holds each, mapping them onto its permission system (Gate::define, a Policy, or spatie/laravel-permission) — see Installation. whoami and list_my_abilities need only an authenticated user.

Quick Start

php artisan mcp-kit:demo                          # seed demo tasks
claude mcp add mcp-kit -- php artisan mcp:start mcp-kit   # connect over STDIO

Set MCP_KIT_LOCAL_USER to the email the local transport should act as. See Quick Start for HTTP and OAuth.

Documentation

Full documentation lives in docs/:

Section	Contents
Getting Started	Installation, gates, first call
Architecture	What the server exposes and the conventions
Authentication	Connecting clients; Sanctum and OAuth 2.1
Configuration	config/mcp-kit.php and MCP_KIT_* reference
Development	Testbench Workbench and testing
Deployment	Running the OAuth transport in production

Testing

composer test

Changelog

See CHANGELOG.md for recent changes.

License

MIT. © Nasrul Hazim / CleaniqueCoders. See LICENSE.md.