README

Introduction

Craft MCP is an MCP (Model Context Protocol) server for Craft CMS. It gives AI assistants direct access to your installation's content, schema, and configuration: rather than describing your field layouts or Matrix setups by hand, the assistant queries them, writes reviewable draft content in a natural-key format, and inspects the system it is working in.

It ships more than 50 specialized tools, 10 analysis prompts, and 13 data resources, served over stdio for local development and over HTTP with scoped bearer tokens for remote users.

Quick Start

Craft MCP is a Craft module in a plain Composer package - no plugin store, no license key, no plugin lifecycle. Requires Craft CMS 5.1+ and PHP 8.3+.

From your Craft root, require it from Packagist:

composer require happy-horizon/craft-mcp:dev-main

The main branch is the only thing published so far, hence dev-main. Composer sets the stability flag for you when the constraint is explicit, so your project's minimum-stability is untouched. Switch to composer require happy-horizon/craft-mcp once a release is tagged.

<?php

use stimmt\craft\Mcp\Mcp;

return [
    'modules' => ['mcp' => Mcp::class],
    'bootstrap' => ['mcp'],
];

Create its tables (idempotent, safe to re-run after updates):

php craft mcp/setup

Enable the server in config/mcp.php (it is disabled in production by default):

<?php

return [
    'enabled' => true,
];

Then run the interactive wizard to configure your MCP clients:

php craft mcp/install

That is the whole happy path. Full install steps, including forks, in-project checkouts, updating, and troubleshooting, are in INSTALL.md. For manual client configuration (Claude Code, Cursor, Claude Desktop, SSH), see the Client Setup guide; for all options including tool disabling, IP allowlists, and environment defaults, see the Configuration guide.

Installation Prompt

Rather have an assistant do it? Paste this into Claude Code, Cursor, or any coding agent with shell access to your Craft project:

Install the Craft MCP module (https://packagist.org/packages/happy-horizon/craft-mcp) into
this Craft CMS project. Work from the Craft root - the directory holding composer.json,
config/ and the craft executable. Verify Craft is 5.1+ and PHP is 8.3+ before starting, and
stop and tell me if either is too old.

1. Require the package. There is no stable tag on Packagist yet, so the constraint must be
   explicit:

       composer require happy-horizon/craft-mcp:dev-main

   If Composer asks to allow the php-http/discovery plugin, allow it - it is part of the
   PSR-7 stack the MCP SDK uses.

2. Register the module in config/app.php. Merge into the existing return array rather than
   overwriting it, and keep any modules that are already registered:

       use stimmt\craft\Mcp\Mcp;

       return [
           'modules' => ['mcp' => Mcp::class],
           'bootstrap' => ['mcp'],
       ];

   The module id must stay 'mcp' (routes, templates, console commands and translations are
   keyed to it) and 'mcp' must be in 'bootstrap', not just 'modules'.

3. Run the migrations:

       php craft mcp/setup

   Prefix with `ddev` if this project uses DDEV.

4. Create or update config/mcp.php so MCP is on in development and off in production:

       return [
           '*' => ['enabled' => false],
           'dev' => ['enabled' => true, 'enableDangerousTools' => true],
       ];

5. Run `php craft mcp/install` to write the client config. It is an interactive wizard - if
   you cannot answer prompts, tell me to run it myself instead of guessing, and point me at
   docs/client-setup.md in the installed package for the manual config.

Then confirm the install: `php craft mcp/setup` should report MCP as enabled. Report back
what you changed, what the wizard wrote, and anything you skipped.

Remote Access over HTTP

Content editors and office users can point Claude Desktop straight at a remote install: the module serves the MCP protocol from a Craft endpoint, authenticated with per-user bearer tokens scoped to readonly, content, or full access. Off by default; enabling it, minting tokens (php craft mcp/tokens/create), and troubleshooting are covered in the HTTP Transport guide.

Content Writing for Agents

Entry reads and writes share one payload format: relations as natural keys ({"section": "pages", "slug": "about"}), Matrix blocks by type handle, and per-field input shapes from describe_entry_schema that tell an agent exactly what every field accepts, third-party fields included. Writes land as reviewable drafts with a control panel deep link, and publish_entry makes them live. The full format, workflow, and schema discovery are covered in the Content Writing guide.

The Toolbox

Category	Highlights
Content	Entries (payload-format read/write, field/relation/date filters, count and group-by breakdowns, draft workflow with a pending-drafts review queue and revision history, publish/duplicate/copy to site), schema discovery via `describe_entry_schema`, assets, categories, users, globals
System	System info, config, logs, caches, routes, console commands
Database	Schema inspection, table counts, read-only queries
Debugging	Queue jobs, project config diff, deprecations, EXPLAIN, event handlers, and a Tinker tool for executing PHP in the Craft context
Multi-Site	Sites, site groups, per-site details
GraphQL	Schemas, SDL, read-only and mutating query execution, tokens
Backup	Create and list database backups
Self-Awareness	Module info, tool listing with risk annotations, hot reload
Commerce	Products, orders, and statuses (when Craft Commerce is installed)

Tools that modify data or execute code are flagged dangerous: they sit behind the enableDangerousTools setting, carry a destructiveHint annotation in tools/list, and are excluded from readonly and (except entry workflow) content HTTP scopes. See the Tools Overview for the complete reference.

Extending

Other plugins and modules can register their own tools, prompts, resources, and field translators through events (EVENT_REGISTER_TOOLS, EVENT_REGISTER_FIELD_TRANSLATORS, and friends). See the Extending guide for implementation details and examples.

Documentation

The documentation index links everything; the direct routes:

Installation - Requirements, Composer setup, detailed installation steps
Client Setup - Wizard and manual configs for Claude Code, Cursor, Claude Desktop
Configuration - All configuration options and security settings
HTTP Transport - Remote access with per-user scoped bearer tokens
Content Writing - The payload format, draft workflow, and schema discovery for agents
Tools Reference - Complete documentation for every tool
Prompts - Pre-built analysis prompts
Resources - Read-only URI-based access to schema, config, and content data
Extending - Register custom tools, prompts, resources, and field translators

Contributing

Thank you for considering contributing to Craft MCP! Please use GitHub Issues on this fork for bug reports, feature requests, and discussion.

Credits

Created and maintained by Max van Essen
Packaged as a Craft module and distributed by Happy Horizon
Inspired by Laravel Boost
Icon from Lucide (MIT)

License

Craft MCP is open-sourced software licensed under the MIT license.

happy-horizon / craft-mcp

Package info

Security

Statistics