PHPackages                             upassist/neos-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. [API Development](/categories/api)
4. /
5. upassist/neos-mcp

ActiveNeos-package[API Development](/categories/api)

upassist/neos-mcp
=================

HTTP bridge for AI-assisted Neos CMS content management via MCP

2.0.4(2mo ago)215MITPHP

Since Mar 25Pushed 3w agoCompare

[ Source](https://github.com/UpAssist/neos-mcp)[ Packagist](https://packagist.org/packages/upassist/neos-mcp)[ Docs](https://github.com/UpAssist/neos-mcp)[ RSS](/packages/upassist-neos-mcp/feed)WikiDiscussions main Synced 4w ago

READMEChangelogDependencies (4)Versions (10)Used By (0)

UpAssist.Neos.Mcp
=================

[](#upassistneosmcp)

**Let AI assistants manage your Neos CMS content** — safely, with human review before anything goes live.

This package adds an HTTP bridge to your Neos CMS installation that AI tools like Claude Code and Cursor can connect to via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io). The AI can read pages, create and edit content, manage assets, and generate preview links. All changes are staged in a separate workspace so an editor can review before publishing.

How it works
------------

[](#how-it-works)

```
AI Assistant (Claude Code, Cursor, etc.)
    │
    │  MCP protocol (stdio)
    │
neos-mcp-client              ← translates MCP ↔ HTTP
    │
    │  HTTP + Bearer token
    │
UpAssist.Neos.Mcp bridge     ← this package (runs inside Neos)
    │
    │  ContentRepository API
    │
Neos CMS (mcp workspace → live)

```

There are two components to install:

1. **This package** (`upassist/neos-mcp`) — a Neos Flow package that exposes content operations as a REST API
2. **The MCP server** ([`@upassist/neos-mcp`](https://github.com/UpAssist/neos-mcp-client)) — a lightweight Node.js process that translates between MCP protocol and the REST API

Quick start
-----------

[](#quick-start)

### 1. Install the Neos package

[](#1-install-the-neos-package)

```
composer require upassist/neos-mcp
```

### 2. Generate a shared token

[](#2-generate-a-shared-token)

The bridge uses a Bearer token to authenticate requests. Generate a secure token and add it to your Neos `.env` file:

```
# Generate a random token
openssl rand -hex 32
```

```
# .env
NEOS_MCP_BRIDGE_TOKEN=paste-your-generated-token-here
```

### 3. Install the MCP server

[](#3-install-the-mcp-server)

The MCP server is a small Node.js application that runs locally on the developer's machine. See the [neos-mcp-client README](https://github.com/UpAssist/neos-mcp-client) for detailed installation and configuration instructions per editor.

**Quick version for Claude Code:**

```
npm install -g @upassist/neos-mcp
```

Add a `.mcp.json` to your Neos project root:

```
{
  "mcpServers": {
    "neos-local": {
      "command": "neos-mcp",
      "env": {
        "NEOS_MCP_URL": "http://localhost:8081",
        "NEOS_MCP_TOKEN": "paste-your-generated-token-here"
      }
    }
  }
}
```

> **Important:** Add `.mcp.json` to `.gitignore` — it contains your token.

### 4. Try it out

[](#4-try-it-out)

Start your Neos instance, open Claude Code (or Cursor), and ask:

> "Show me the pages on my Neos site"

The AI will call `neos_get_site_context` and show you the site structure. From there you can ask it to edit content, create pages, upload images, and more — all staged for your review.

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

[](#requirements)

VersionNeos CMSPHPBranchv2.x9.0+8.2+`main` (this branch)v1.x8.38.1+`neos-8`Node.js 18+ is required for the MCP server in both versions.

Configuration
-------------

[](#configuration)

The default settings work out of the box. The only required configuration is the API token in your `.env` file (see step 2 above).

### Workspace

[](#workspace)

All content changes are written to a dedicated **mcp** workspace (branched from `live`). This workspace is created automatically on first use. Changes remain there until explicitly published — the AI never auto-publishes to live.

### Authentication

[](#authentication)

Every request to the bridge must include a Bearer token:

```
Authorization: Bearer

```

By default, authenticated requests get **Neos.Neos:Administrator** privileges. To restrict this to Editor privileges, add to your site's `Settings.yaml`:

```
Neos:
  Flow:
    security:
      authentication:
        providers:
          'UpAssist.Neos.Mcp:ApiToken':
            providerOptions:
              authenticateRoles:
                - 'Neos.Neos:Editor'
```

### Full settings reference

[](#full-settings-reference)

```
UpAssist:
  Neos:
    Mcp:
      apiToken: '%env:NEOS_MCP_BRIDGE_TOKEN%'
      mcpWorkspaceName: 'mcp'
      mcpWorkspaceTitle: 'MCP Review'
      mcpWorkspaceDescription: 'Shared workspace for AI-assisted content changes, pending human review'
```

What the AI can do
------------------

[](#what-the-ai-can-do)

Once connected, the AI assistant has access to these capabilities:

### Read content

[](#read-content)

ToolDescription`neos_get_site_context`Get site structure, all node types with properties, and page tree`neos_list_pages`List all pages in a workspace`neos_get_page_content`Get all content nodes on a specific page`neos_get_document_properties`Get page-level properties (title, SEO fields, etc.)`neos_list_node_types`List available node types and their properties### Create and edit content

[](#create-and-edit-content)

ToolDescription`neos_update_node_property`Update a property on an existing node (text, images, metadata)`neos_create_content_node`Create a new content element inside a page`neos_create_document_node`Create a new page`neos_move_node`Move a node to a new position`neos_delete_node`Remove a node### Manage assets

[](#manage-assets)

ToolDescription`neos_list_assets`Browse the Media Manager (filter by type, tag)`neos_list_asset_tags`List available asset tags### Review and publish

[](#review-and-publish)

ToolDescription`neos_get_preview_url`Generate a 24-hour preview link (no Neos login needed)`neos_list_pending_changes`See what has been changed`neos_publish_changes`Publish all changes from workspace to live### Typical AI workflow

[](#typical-ai-workflow)

```
1. neos_get_site_context       → Understand the site
2. neos_get_page_content       → Read current content
3. neos_update_node_property   → Make changes
4. neos_get_preview_url        → Generate preview for human review
5. (human reviews the preview)
6. neos_publish_changes        → Go live after confirmation

```

Entity CRUD (advanced)
----------------------

[](#entity-crud-advanced)

Beyond Neos content nodes, the bridge can also expose custom Doctrine entities for CRUD operations. This is useful for managing data stored in custom database tables (e.g. notifications, form submissions, product data).

Packages declare their entities in YAML — no code changes in the bridge itself:

```
UpAssist:
  Neos:
    Mcp:
      entities:
        notifications:
          label: 'Editor Notifications'
          className: 'Vendor\Package\Domain\Model\Notification'
          repository: 'Vendor\Package\Domain\Repository\NotificationRepository'
          service: 'Vendor\Package\Service\NotificationService'  # optional

          fields:
            title:
              type: string
              label: 'Title'
              required: true
            content:
              type: markdown
              label: 'Content'
            status:
              type: enum
              enum: [draft, active, archived]
```

Once configured, the AI gets access to generic entity tools: `neos_entity_discover`, `neos_entity_list`, `neos_entity_show`, `neos_entity_create`, `neos_entity_update`, `neos_entity_delete`, and `neos_entity_action`.

### Supported field types

[](#supported-field-types)

TypeDescription`string`, `text`, `markdown`Text fields`integer`, `float`Numeric fields`boolean`Boolean (also accepts string "true"/"false")`datetime`ISO 8601 date/time`reference`UUID reference to another entity`asset`Reference to a Neos asset (by UUID)`enum`Validated against a list of allowed values`json`JSON data### Service delegation

[](#service-delegation)

When a `service` and `serviceMethods` are configured, CRUD operations are routed through a service class instead of direct repository calls. This preserves business logic like validation, markdown rendering, and side effects. Use `parameterMapping` when service method parameters differ from field names.

Full entity configuration reference```
UpAssist:
  Neos:
    Mcp:
      entities:
        myEntity:
          label: 'My Entity'
          className: 'Vendor\Package\Domain\Model\MyEntity'
          repository: 'Vendor\Package\Domain\Repository\MyEntityRepository'
          service: 'Vendor\Package\Service\MyEntityService'

          fields:
            title:
              type: string
              label: 'Title'
              required: true

          filters:
            active:
              label: 'Active items'
              method: 'findActive'
            byStatus:
              label: 'Filter by status'
              method: 'findByFilter'
              parameters:
                filter:
                  type: string
                  required: true

          actions:
            publish:
              label: 'Publish'
              method: 'publish'
              serviceMethod: true
              requiresEntity: true

          serviceMethods:
            create:
              method: 'createEntity'
              parameterMapping:
                content: 'contentMarkdown'
            update:
              method: 'updateEntity'
              parameterMapping:
                content: 'contentMarkdown'
            delete:
              method: 'delete'
```

Review Status (opt-in)
----------------------

[](#review-status-opt-in)

The package includes an optional review workflow that shows editors which pages were modified by AI and what changed.

### Enabling

[](#enabling)

Add the mixin to your Document node types:

```
'Your.Site:Mixin.Document':
  superTypes:
    'UpAssist.Neos.Mcp:Mixin.ReviewStatus': true
```

### What it does

[](#what-it-does)

- **Automatic change tracking** — When content is modified via MCP, the closest Document node is marked as "needs review" with a changelog of what changed
- **Visual indicators** — Orange dots appear in the Neos document tree and inspector for pages needing review
- **Translated changelog** — Property changes show translated labels (e.g. "Property 'Keywords' changed" instead of raw property names)
- **Approval workflow** — When an editor sets the status to "Approved", the changelog is automatically cleared

The Review tab in the inspector shows:

- **Status**: Approved / Needs Review
- **Last changed**: When the AI last modified the page
- **Changelog**: List of changes since last approval

API reference
-------------

[](#api-reference)

Full REST API documentationAll endpoints are available under `/neos/mcp/` and accept/return JSON. Every request requires a `Authorization: Bearer ` header.

### GET /neos/mcp/getSiteContext

[](#get-neosmcpgetsitecontext)

Returns site info, all node types with properties, and the page tree. Typically the first call an MCP client makes.

### POST /neos/mcp/setupWorkspace

[](#post-neosmcpsetupworkspace)

Creates the MCP workspace if it doesn't exist.

### POST /neos/mcp/listPages

[](#post-neosmcplistpages)

List all document nodes. Optional parameter: `workspace` (default: `mcp`).

### POST /neos/mcp/getPageContent

[](#post-neosmcpgetpagecontent)

Get all content nodes for a page. Parameters: `nodePath` (required), `workspace` (default: `mcp`).

### POST /neos/mcp/getDocumentProperties

[](#post-neosmcpgetdocumentproperties)

Get document-level properties. Parameters: `nodePath` (required), `workspace` (default: `mcp`).

### POST /neos/mcp/listNodeTypes

[](#post-neosmcplistnodetypes)

List available node types. Parameter: `filter` — `content`, `document`, or `all` (default: `content`).

### POST /neos/mcp/updateNodeProperty

[](#post-neosmcpupdatenodeproperty)

Update a single property on a node. Parameters: `contextPath` (required), `property` (required), `value` (required), `workspace` (default: `mcp`). For image/asset properties, pass the asset UUID — it will be resolved automatically.

### POST /neos/mcp/createContentNode

[](#post-neosmcpcreatecontentnode)

Create a content node. Parameters: `parentPath` (required), `nodeType` (required), `properties` (optional), `workspace` (default: `mcp`).

### POST /neos/mcp/createDocumentNode

[](#post-neosmcpcreatedocumentnode)

Create a page. Parameters: `parentPath` (required), `nodeType` (required), `properties` (optional), `workspace` (default: `mcp`), `nodeName` (optional), `insertBefore`/`insertAfter` (optional).

### POST /neos/mcp/moveNode

[](#post-neosmcpmovenode)

Move a node. Parameters: `contextPath` (required), plus exactly one of: `insertBefore`, `insertAfter`, or `newParentPath`. Optional: `workspace` (default: `mcp`).

### POST /neos/mcp/deleteNode

[](#post-neosmcpdeletenode)

Remove a node. Parameters: `contextPath` (required), `workspace` (default: `mcp`).

### POST /neos/mcp/listPendingChanges

[](#post-neosmcplistpendingchanges)

List unpublished changes. Parameter: `workspace` (default: `mcp`).

### POST /neos/mcp/getPreviewUrl

[](#post-neosmcpgetpreviewurl)

Generate a 24-hour preview URL. Parameters: `nodePath` (required), `workspace` (default: `mcp`).

### GET /neos/mcp/listAssets

[](#get-neosmcplistassets)

List assets from Media Manager. Parameters: `mediaType` (default: `image`), `tag`, `limit` (default: `50`), `offset` (default: `0`).

### GET /neos/mcp/listAssetTags

[](#get-neosmcplistassettags)

List all asset tags.

### POST /neos/mcp/publishChanges

[](#post-neosmcppublishchanges)

Publish all pending changes to live. Parameter: `workspace` (default: `mcp`).

### Entity endpoints

[](#entity-endpoints)

All at `/neos/mcp/entity/`, using Bearer token auth:

EndpointMethodDescription`listentities`GETDiscover all exposed entities with schemas`list`POSTList/filter entities`show`POSTGet single entity by UUID`create`POSTCreate new entity`update`POSTUpdate entity properties`delete`POSTDelete entity`execute`POSTRun a named actionArchitecture
------------

[](#architecture)

Internal componentsComponentPurpose`McpBridgeController`REST API endpoints for all content operations`ApiTokenProvider`Flow security authentication provider (Bearer token to Neos roles)`PreviewTokenMiddleware`HTTP middleware that activates workspace preview from `?_mcpPreview=` tokens`PreviewTokenService`Singleton holding the active preview workspace for the current request`WorkspacePreviewAspect`AOP aspect that switches ContentRepository context to the preview workspace`ReviewStatusService`Tracks MCP changes, creates changelog entries, clears on approval`ReviewStatusNodeInfoAspect`Injects review status into Neos UI tree node data### Preview mechanism

[](#preview-mechanism)

1. `PreviewTokenMiddleware` reads the `_mcpPreview` query parameter
2. Validates the token against cache (24h TTL)
3. Activates the preview workspace via `PreviewTokenService`
4. `WorkspacePreviewAspect` intercepts `ContextFactory->create()` and switches to the preview workspace
5. The page renders normally — hidden content is **not** shown in previews

License
-------

[](#license)

MIT

###  Health Score

39

—

LowBetter than 85% of packages

Maintenance91

Actively maintained with recent releases

Popularity10

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity40

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 ~4 days

Total

8

Last Release

68d ago

Major Versions

0.2.0 → 1.0.02026-04-01

1.0.0 → 2.0.02026-04-03

1.0.1 → 2.0.32026-04-23

### Community

Maintainers

![](https://www.gravatar.com/avatar/0644de5e880c5b511c6b1cb1b08c80be5a64afd16d37dd9e633aa32c2d49f4cd?d=identicon)[hphoeksma](/maintainers/hphoeksma)

---

Top Contributors

[![hphoeksma](https://avatars.githubusercontent.com/u/250683?v=4)](https://github.com/hphoeksma "hphoeksma (36 commits)")

### Embed Badge

![Health badge](/badges/upassist-neos-mcp/health.svg)

```
[![Health](https://phpackages.com/badges/upassist-neos-mcp/health.svg)](https://phpackages.com/packages/upassist-neos-mcp)
```

###  Alternatives

[neos/neos

An open source Content Application Platform based on Flow. A set of core Content Management features is resting within a larger context that allows you to build a perfectly customized experience for your users.

1151.0M753](/packages/neos-neos)[flowpack/media-ui

This module allows managing media assets including pictures, videos, audio and documents.

2194.5k2](/packages/flowpack-media-ui)[neos/media

The Media package

101.2M53](/packages/neos-media)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)