PHPackages jaapmoolenaar.nl/laravel-unsplash-mcp - 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. [Utility & Helpers](/categories/utility) 4. / 5. jaapmoolenaar.nl/laravel-unsplash-mcp ActiveLibrary[Utility & Helpers](/categories/utility) jaapmoolenaar.nl/laravel-unsplash-mcp ===================================== Unsplash MCP tools for Laravel v1.0.1(2w ago)03MITPHPPHP ^8.4CI passing Since May 20Pushed 2w agoCompare [ Source](https://github.com/JaapMoolenaar/laravel-unsplash-mcp)[ Packagist](https://packagist.org/packages/jaapmoolenaar.nl/laravel-unsplash-mcp)[ RSS](/packages/jaapmoolenaarnl-laravel-unsplash-mcp/feed)WikiDiscussions master Synced 1w ago READMEChangelog (2)Dependencies (5)Versions (3)Used By (0) Unsplash MCP for Laravel ======================== [](#unsplash-mcp-for-laravel) A Laravel package that exposes Unsplash photo search and import as an [MCP](https://github.com/laravel/mcp) (Model Context Protocol) server. Designed for use with Statamic: an AI assistant can search Unsplash, pick a photo, and download it directly into the Statamic asset library — including attribution metadata. Requirements ------------ [](#requirements) - PHP 8.4+ - Laravel 13+ - [`laravel/mcp`](https://github.com/laravel/mcp) ≥ 0.1 Installation ------------ [](#installation) ``` composer require jaapmoolenaar.nl/laravel-unsplash-mcp ``` The service provider is auto-discovered and registers the MCP server automatically. Configuration ------------- [](#configuration) Add your Unsplash API access key to your `.env`: ``` UNSPLASH_ACCESS_KEY=your-unsplash-access-key ``` You can get an access key by creating an application at [unsplash.com/developers](https://unsplash.com/developers). Optionally publish the config file if you need to customise it: ``` php artisan vendor:publish --tag=unsplash-mcp-config ``` ### All environment variables [](#all-environment-variables) VariableDefaultDescription`UNSPLASH_ACCESS_KEY`—Your Unsplash API access key (required)`UNSPLASH_REGISTRAR``disk`Default registrar used by `import-unsplash-photo``UNSPLASH_TEMP_DISK``local`Temporary disk used while downloading before moving`UNSPLASH_DISK``public`Target disk for the `disk` registrar`UNSPLASH_STATAMIC_CONTAINER``assets`Asset container handle for the `statamic` registrarMCP Server ---------- [](#mcp-server) The package registers a local MCP server named `unsplash` with two tools: ### `search-unsplash` [](#search-unsplash) Search Unsplash for photos by keyword. Returns paginated results with photo IDs, image URLs, descriptions, and photographer attribution. ParameterTypeRequiredDescription`query`stringYesSearch keyword or phrase (max 50 characters)`page`integerNoPage number (minimum 1, default 1)`per_page`integerNoResults per page (maximum 30, default 10)`order_by`stringNoSort by `relevant` (default) or `latest``orientation`stringNoFilter by `landscape`, `portrait`, or `squarish`Example response: ``` { "total": 1420, "total_pages": 142, "results": [ { "id": "abc123xyz", "description": "A beautiful nature photo", "alt_description": "green trees in a forest", "urls": { "regular": "https://images.unsplash.com/photo-abc123?w=1080", "small": "https://images.unsplash.com/photo-abc123?w=400", "thumb": "https://images.unsplash.com/photo-abc123?w=200" }, "link": "https://unsplash.com/photos/abc123xyz", "photographer": "Jane Doe", "photographer_url": "https://unsplash.com/@janedoe" } ] } ``` ### `import-unsplash-photo` [](#import-unsplash-photo) Downloads a photo (by ID from `search-unsplash`) and stores it using the configured registrar. Use the `registrar` parameter to control where the photo ends up. ParameterTypeRequiredDescription`photo_id`stringYesThe Unsplash photo ID (from `search-unsplash` results)`basename`stringNoBase filename without extension (default: `unsplash-{photo_id}`)`registrar`stringNoStorage target: `disk` or `statamic` (default: `UNSPLASH_REGISTRAR`)Example response: ``` { "filename": "my-photo.jpg", "url": "https://example.com/storage/my-photo.jpg", "photographer": "Jane Doe" } ``` > **Note:** The download flow follows the [Unsplash API guidelines](https://help.unsplash.com/en/articles/2511258-guideline-triggering-a-download) by triggering the required download event before saving the image. #### Registrars [](#registrars) **`disk`** — stores the photo on the Laravel disk configured by `UNSPLASH_DISK` (defaults to `public`). **`statamic`** — stores the photo in the Statamic asset container configured by `UNSPLASH_STATAMIC_CONTAINER` (defaults to `assets`) and writes Unsplash attribution as asset metadata: ``` unsplash_id: abc123xyz unsplash_photographer: Jane Doe unsplash_photographer_url: https://unsplash.com/@janedoe unsplash_photo_url: https://unsplash.com/photos/abc123xyz unsplash_photo_cdn_url: https://images.unsplash.com/photo-abc123 ``` Requires `statamic/cms` to be installed. Connecting an MCP client ------------------------ [](#connecting-an-mcp-client) The service provider registers the MCP server automatically. How you connect an AI client depends on the transport. ### Stdio: desktop AI tools (recommended) [](#stdio-desktop-ai-tools-recommended) Desktop tools like Claude Code, Cursor, and VS Code connect to MCP servers over stdio. It should start the server with: ``` php artisan mcp:start unsplash ``` You can configure your client to run that command. For **Claude Code**, add this to `.mcp.json` in your project root: ``` { "mcpServers": { "unsplash": { "type": "stdio", "command": "php", "args": ["artisan", "mcp:start", "unsplash"] } } } ``` ### HTTP: web-based clients [](#http-web-based-clients) If your client connects over HTTP, publish the AI routes file and register the server: ``` php artisan vendor:publish --tag=ai-routes ``` Then add to `routes/ai.php`: ``` use Laravel\Mcp\Facades\Mcp; Mcp::web('/mcp/unsplash', \JaapMoolenaar\UnsplashMcp\UnsplashServer::class); ``` The server is then reachable at `POST /mcp/unsplash`. Usage with an AI assistant -------------------------- [](#usage-with-an-ai-assistant) Once the MCP server is active, an AI assistant (e.g. Claude) connected to your Laravel app can: 1. Call `search-unsplash` to find photos matching a description. 2. Pick a result from the list. 3. Call `import-unsplash-photo` with the chosen `id` — pass `registrar=statamic` to import directly into the Statamic asset library. 4. Tell you the filename — open the Statamic CP, go to Assets, and select it for the desired field (e.g. a hero image). Development ----------- [](#development) ### Running the tests [](#running-the-tests) ``` composer test ``` Tests use [Pest](https://pestphp.com/) and [Orchestra Testbench](https://github.com/orchestral/testbench). HTTP calls are intercepted with `Http::fake()` and storage is isolated with `Storage::fake('public')`. ### Code style [](#code-style) This package uses [Laravel Pint](https://github.com/laravel/pint) with the `laravel` preset. ``` composer lint # fix issues composer lint:check # dry-run (useful for CI) ``` ### Health Score 42 — FairBetter than 88% of packages Maintenance96 Actively maintained with recent releases Popularity4 Limited adoption so far Community6 Small or concentrated contributor base Maturity52 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~0 days Total 2 Last Release 19d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/41458824d118b160a0698211b9288090a67f27a4a0f87f3a65b96073decf2b3e?d=identicon)[jaapmoolenaar.nl](/maintainers/jaapmoolenaar.nl) --- Top Contributors [![JaapMoolenaar](https://avatars.githubusercontent.com/u/2211836?v=4)](https://github.com/JaapMoolenaar "JaapMoolenaar (5 commits)") ### Code Quality TestsPest Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/jaapmoolenaarnl-laravel-unsplash-mcp/health.svg) ``` [![Health](https://phpackages.com/badges/jaapmoolenaarnl-laravel-unsplash-mcp/health.svg)](https://phpackages.com/packages/jaapmoolenaarnl-laravel-unsplash-mcp) ``` ### Alternatives [laravel/boost Laravel Boost accelerates AI-assisted development by providing the essential context and structure that AI needs to generate high-quality, Laravel-specific code. 3.5k17.6M507](/packages/laravel-boost)[binaryk/laravel-restify Laravel REST API helpers 675410.3k](/packages/binaryk-laravel-restify)[joshcirre/instruckt-laravel Visual feedback for AI coding agents — Laravel MCP package 17218.6k2](/packages/joshcirre-instruckt-laravel) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)