README

This package presents a remote MCP server for Statamic v6, which makes it possible to manage your content (entries, taxonomy terms, globals, and assets) via any AI provider. Statamic's permission system is deciding who may do what. Built on the first-party laravel/mcp package.

Requirements

• PHP ^8.3
• Statamic ^6.0 (Laravel 12 or 13)
• For OAuth mode only: laravel/passport + database (Eloquent) users

Installation

composer require danielgnh/statamic-mcp

That's it — no config publishing required.

The connected user needs the Access MCP permission (or super). Grant it in the Control Panel under the role's permissions — mcp:token warns you at issuance if the user doesn't have it yet.

Prefer a guided setup? One interactive command handles either auth mode — including every OAuth prerequisite — and finishes by running mcp:doctor as proof:

php please mcp:setup

It's scriptable too — --oauth --yes (or --token --user=you@site.com --yes) runs unattended, which is what the bundled Laravel Boost guidelines teach AI coding agents to use. Boost users get them automatically on boost:install.

Token vs. OAuth mode

What Statamic MCP can do?

19 tools across five areas — every agent session is starting with statamic_overview, which reports the sites, resources, and capabilities visible to the acting user:

• Discovery — statamic_overview, blueprints_get (fields + a valid example payload for writes)
• Entries — entries_list, entries_get, entries_create, entries_update, entries_delete
• Taxonomy terms — terms_list, terms_get, terms_create, terms_update, terms_delete
• Globals — globals_get, globals_update
• Assets — assets_list, assets_get, assets_upload, assets_update, assets_delete

The write semantics are deliberately conservative:

• Entry creates and updates save drafts by default — agents draft, humans publish.
• On revision-enabled collections, edits become working copies through the same mechanism the CP uses; the live entry is never touched.
• Delete tools aren't even registered unless you opt in (deletes config).
• Every write response states the resulting liveness ("saved as draft — not live", "working copy created — live entry unchanged", …) and links the CP edit page.

See docs/tools.md for the full per-tool reference, including upload limits and the SSRF policy for URL-based asset uploads.

Authentication

Token mode (default)

Works on every install, including file-based users. Tokens are stored SHA-256-hashed in storage/statamic/mcp/tokens.yaml — no database, no migrations — and shown exactly once at issuance. A token authenticates as the Statamic user it was issued for; delete the user and the token dies with them.

php please mcp:token you@site.com --name="Claude" --expires-days=90   # issue
php please mcp:tokens                                                 # list
php please mcp:token:revoke {tokenId}                                 # revoke

Users can also issue and revoke their own tokens in the Control Panel at Tools → Utilities → MCP Access — grant the Access MCP Tokens utility permission to enable it. Super admins see (and can revoke) everyone's tokens.

OAuth mode

For claude.ai, Claude Desktop, and ChatGPT connectors. Delegates everything to laravel/mcp + Laravel Passport (dynamic client registration, PKCE, consent screen) — this addon ships zero OAuth code. It requires database (Eloquent) users, because Passport does.

The easy path is the wizard:

php please mcp:setup

It migrates users to the database, installs Passport, prepares the user model, adds the api guard, and flips STATAMIC_MCP_AUTH=oauth — never editing a file without showing the change first. The manual steps, plus the CP panel for viewing and disconnecting OAuth connections, are in docs/oauth.md.

If any prerequisite is missing, the MCP endpoint answers 503 with the exact remedy — the rest of your site is untouched.

Configuration

php artisan vendor:publish --tag=statamic-mcp-config   # → config/statamic/mcp.php

Upgrading from v1.0? Re-publish the config or add 'asset_containers' => true to resources — a published config without the key exposes no containers (safe by default).

Security model: the token is the user

There are no API scopes and no parallel ACL. Every MCP request authenticates as a real Statamic user, and authorization is always Statamic's native permission system — the same roles UI you already use:

1. Read-only switch — read_only hides all write/delete tools.
2. Exposure allowlist — resources decides what exists as far as MCP is concerned.
3. Native permissions on every call — view/edit/create/delete {handle} entries (and term/global equivalents), publish permissions for publish-state changes, site permissions on multi-site. Denials name the missing permission and the remedy.
4. Deletes off by default — both the config flag and the role permission must open.

A restricted agent is just a dedicated Statamic user with a restricted role. Ready-made recipes — drafting agent, read-only analyst, publishing agent, site scoping — are in docs/permissions.md.

Troubleshooting

php please mcp:doctor

One command answers "why doesn't my MCP endpoint work?" — it runs every check without short-circuiting and names each problem with the exact remedy.

Details on every doctor check, and the MCP Inspector, are in docs/troubleshooting.md.

Testing

composer test     # Pest
composer format   # Pint

License

MIT — see LICENSE.md.