PHPackages                             opgginc/laravel-mcp-server - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. opgginc/laravel-mcp-server

ActiveLibrary

opgginc/laravel-mcp-server
==========================

This is my package laravel-mcp-server

v2.0.5(2mo ago)33143.5k↑18%30[3 issues](https://github.com/opgginc/laravel-mcp-server/issues)[1 PRs](https://github.com/opgginc/laravel-mcp-server/pulls)MITPHPPHP ^8.2CI passing

Since Apr 17Pushed 1mo ago7 watchersCompare

[ Source](https://github.com/opgginc/laravel-mcp-server)[ Packagist](https://packagist.org/packages/opgginc/laravel-mcp-server)[ Docs](https://github.com/opgginc/laravel-mcp-server)[ RSS](/packages/opgginc-laravel-mcp-server/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (14)Versions (41)Used By (0)

Laravel MCP Server by OP.GG
===========================

[](#laravel-mcp-server-by-opgg)

 Build a route-first MCP server in Laravel and Lumen

[![Build Status](https://github.com/opgginc/laravel-mcp-server/actions/workflows/tests.yml/badge.svg)](https://github.com/opgginc/laravel-mcp-server/actions)[![Total Downloads](https://camo.githubusercontent.com/038632a1212e4ec60f77e9adafc97e808666937e7455d825d9eb98ecae80234c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6f706767696e632f6c61726176656c2d6d63702d736572766572)](https://packagist.org/packages/opgginc/laravel-mcp-server)[![Latest Stable Version](https://camo.githubusercontent.com/343348be789df6c41bc0824a3646900850d1438e06cbb5573e25dd5528b09772/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6f706767696e632f6c61726176656c2d6d63702d736572766572)](https://packagist.org/packages/opgginc/laravel-mcp-server)[![License](https://camo.githubusercontent.com/712385ebb07b2b6700d954992de65068ae705f5c88aeab217a690582cbb5ae94/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6f706767696e632f6c61726176656c2d6d63702d736572766572)](https://packagist.org/packages/opgginc/laravel-mcp-server)

[Official Website](https://op.gg/open-source/laravel-mcp-server)

 [English](README.md) | [Português do Brasil](README.pt-BR.md) | [한국어](README.ko.md) | [Русский](README.ru.md) | [简体中文](README.zh-CN.md) | [繁體中文](README.zh-TW.md) | [Polski](README.pl.md) | [Español](README.es.md)

 [![Laravel MCP Server Demo](docs/watch.gif)](docs/watch.gif)

Breaking Changes 2.0.0
----------------------

[](#breaking-changes-200)

- Endpoint setup moved from config-driven registration to route-driven registration.
- Streamable HTTP is the only supported transport.
- Server metadata mutators are consolidated into `setServerInfo(...)`.
- Legacy tool transport methods were removed from runtime (`messageType()`, `ProcessMessageType::SSE`).

Full migration guide: [docs/migrations/v2.0.0-migration.md](docs/migrations/v2.0.0-migration.md)

Overview
--------

[](#overview)

Laravel MCP Server provides route-based MCP endpoint registration for Laravel and Lumen.

Key points:

- Streamable HTTP transport
- Route-first configuration (`Route::mcp(...)` / `McpRoute::register(...)`)
- Tool, resource, resource template, and prompt registration per endpoint
- Route cache compatible endpoint metadata

Requirements
------------

[](#requirements)

- PHP >= 8.2
- Laravel (Illuminate) >= 9.x
- Lumen >= 9.x (optional)

Quick Start
-----------

[](#quick-start)

### 1) Install

[](#1-install)

```
composer require opgginc/laravel-mcp-server
```

### 2) Register an endpoint (Laravel)

[](#2-register-an-endpoint-laravel)

```
use Illuminate\Support\Facades\Route;
use OPGG\LaravelMcpServer\Enums\ProtocolVersion;
use OPGG\LaravelMcpServer\Services\ToolService\Examples\HelloWorldTool;
use OPGG\LaravelMcpServer\Services\ToolService\Examples\VersionCheckTool;

Route::mcp('/mcp')
    ->setServerInfo(
        name: 'OP.GG MCP Server',
        version: '2.0.0',
    )
    ->setConfig(
        compactEnumExampleCount: 3,
    )
    ->setProtocolVersion(ProtocolVersion::V2025_11_25)
    ->enabledApi()
    ->tools([
        HelloWorldTool::class,
        VersionCheckTool::class,
    ]);
```

If you need compatibility with clients that do not support `2025-11-25`, set:

```
->setProtocolVersion(ProtocolVersion::V2025_06_18)
```

### 3) Verify

[](#3-verify)

```
php artisan route:list | grep mcp
php artisan mcp:test-tool --list --endpoint=/mcp
```

Quick JSON-RPC check:

```
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

Lumen Setup
-----------

[](#lumen-setup)

```
// bootstrap/app.php
$app->withFacades();
$app->withEloquent();
$app->register(OPGG\LaravelMcpServer\LaravelMcpServerServiceProvider::class);
```

```
use OPGG\LaravelMcpServer\Routing\McpRoute;
use OPGG\LaravelMcpServer\Services\ToolService\Examples\HelloWorldTool;

McpRoute::register('/mcp')
    ->setServerInfo(
        name: 'OP.GG MCP Server',
        version: '2.0.0',
    )
    ->tools([
        HelloWorldTool::class,
    ]);
```

Minimal Security (Production)
-----------------------------

[](#minimal-security-production)

Use Laravel middleware on your MCP route group.

```
use Illuminate\Support\Facades\Route;

Route::middleware([
    'auth:sanctum',
    'throttle:100,1',
])->group(function (): void {
    Route::mcp('/mcp')
        ->setServerInfo(
            name: 'Secure MCP',
            version: '2.0.0',
        )
        ->tools([
            \App\MCP\Tools\MyCustomTool::class,
        ]);
});
```

v2.0.0 Migration Notes (from v1.0.0)
------------------------------------

[](#v200-migration-notes-from-v100)

- MCP endpoint setup moved from config to route registration.
- Streamable HTTP is the only transport.
- Server metadata mutators are consolidated into `setServerInfo(...)`.
- Tool migration command is available for legacy signatures:

```
php artisan mcp:migrate-tools
```

Full guide: [docs/migrations/v2.0.0-migration.md](docs/migrations/v2.0.0-migration.md)

Advanced Features (Quick Links)
-------------------------------

[](#advanced-features-quick-links)

- Create tools: `php artisan make:mcp-tool ToolName`
- Create resources: `php artisan make:mcp-resource ResourceName`
- Create resource templates: `php artisan make:mcp-resource-template TemplateName`
- Create prompts: `php artisan make:mcp-prompt PromptName`
- Create notifications: `php artisan make:mcp-notification HandlerName --method=notifications/method`
- Generate from OpenAPI: `php artisan make:swagger-mcp-tool `
- Export tools to OpenAPI: `php artisan mcp:export-openapi --output=storage/api-docs-mcp/api-docs.json`

Code references:

- Tool examples: `src/Services/ToolService/Examples/`
- Resource examples: `src/Services/ResourceService/Examples/`
- Prompt service: `src/Services/PromptService/`
- Notification handlers: `src/Server/Notification/`
- Route builder: `src/Routing/McpRouteBuilder.php`

Swagger/OpenAPI -> MCP Tool
------------------------------

[](#swaggeropenapi---mcp-tool)

Generate MCP tools from a Swagger/OpenAPI spec:

```
# From URL
php artisan make:swagger-mcp-tool https://api.example.com/openapi.json

# From local file
php artisan make:swagger-mcp-tool ./specs/openapi.json
```

Useful options:

```
php artisan make:swagger-mcp-tool ./specs/openapi.json \
  --group-by=tag \
  --prefix=Billing \
  --test-api
```

- `--group-by`: `tag`, `path`, or `none`
- `--prefix`: class-name prefix for generated tools/resources
- `--test-api`: test endpoint connectivity before generation

Generation behavior:

- In interactive mode, you can choose Tool or Resource per endpoint.
- In non-interactive mode, `GET` endpoints are generated as Resources and other methods as Tools.

### Enhanced Interactive Preview

[](#enhanced-interactive-preview)

If you run the command without `--group-by`, the generator shows an interactive preview of folder structure and file counts before creation.

```
php artisan make:swagger-mcp-tool ./specs/openapi.json
```

Example preview output:

```
Choose how to organize your generated tools and resources:

Tag-based grouping (organize by OpenAPI tags)
  Total: 25 endpoints -> 15 tools + 10 resources
  Examples: Tools/Pet, Tools/Store, Tools/User

Path-based grouping (organize by API path)
  Total: 25 endpoints -> 15 tools + 10 resources
  Examples: Tools/Api, Tools/Users, Tools/Orders

No grouping (everything in root folder)
  Total: 25 endpoints -> 15 tools + 10 resources
  Examples: Tools/, Resources/

```

After generation, register generated tool classes on your MCP endpoint:

```
use Illuminate\Support\Facades\Route;

Route::mcp('/mcp')
    ->setServerInfo(
        name: 'Generated MCP Server',
        version: '2.0.0',
    )
    ->tools([
        \App\MCP\Tools\Billing\CreateInvoiceTool::class,
        \App\MCP\Tools\Billing\UpdateInvoiceTool::class,
    ]);
```

MCP Tools -> OpenAPI Export
------------------------------

[](#mcp-tools---openapi-export)

Export all registered `ToolInterface` classes (via `Route::mcp(...)->tools([...])`) to an OpenAPI JSON document using each tool's `inputSchema()`. Only endpoints configured with `->enabledApi()` are included in this export and exposed through `POST /tools/{tool_name}`. Operations are grouped by endpoint `name` using OpenAPI `tags`. If multiple endpoints register the same tool name, the operation keeps first-registration behavior and merges all matching endpoint names into `tags`. If route registration is missing, the command auto-discovers tools under default paths: `app/MCP/Tools` and `app/Tools`.

```
# Default output: storage/api-docs-mcp/api-docs.json
php artisan mcp:export-openapi

# Custom output + metadata
php artisan mcp:export-openapi \
  --output=storage/app/mcp.openapi.json \
  --title="MCP Tools API" \
  --api-version=2.1.0

# Limit to one endpoint (id or path)
php artisan mcp:export-openapi --endpoint=/mcp

# Discover tools from additional directory paths
php artisan mcp:export-openapi --discover-path=app/MCP/Tools

# Existing output is overwritten by default
php artisan mcp:export-openapi
```

Enable Tool API route generation:

```
use Illuminate\Support\Facades\Route;

Route::mcp('/mcp')
    ->setServerInfo(name: 'OP.GG MCP Server', version: '2.0.0')
    ->enabledApi()
    ->tools([
        \App\MCP\Tools\GreetingTool::class,
    ]);
```

Swagger UI testing tip:

- Exported operations use `query parameters` only (no `requestBody`) for simpler manual testing.
- Required fields from each tool `inputSchema().required` are reflected in Swagger parameter validation.
- Enum fields are exported with `schema.enum` so Swagger renders dropdown selections.
- Array fields are exported with `style=form` + `explode=true` (repeat key format, e.g. `desired_output_fields=items&desired_output_fields=runes`).
- `/tools/{tool_name}` argument parsing prefers query parameters over body/form payloads to avoid Swagger conflicts.
- Enum fields without explicit `default`/`example` are auto-filled from the first enum value (or first non-null enum value).
- String fields with descriptions like `e.g., en_US, ko_KR, ja_JP` auto-infer first sample value as `default` and `example`.

Example Tool Class
------------------

[](#example-tool-class)

```