📌Overview

Purpose: The Payload CMS 3.0 MCP Server is designed to enhance the development experience for Payload CMS by facilitating code validation, template generation, and project scaffolding.

Overview: This specialized Model Context Protocol server simplifies the development process, enabling developers to adhere to best practices when building applications with Payload CMS 3.0. It incorporates tools for validating code, generating necessary templates, and scaffolding projects efficiently.

Key Features:

Code Validation: Validates Payload CMS code for collections, fields, globals, and configuration files, offering detailed feedback on syntax errors and adherence to best practices.
Code Generation: Automates the creation of code templates for various components such as collections, fields, and hooks, streamlining the setup process and improving consistency in code quality.
Project Scaffolding: Provides the ability to scaffold complete Payload CMS project structures, ensuring validated options that conform to best practices for a standardized development environment.

🚀 Payload CMS 3.0 MCP Server

A specialized MCP server for Payload CMS 3.0

Validate code, generate templates, and scaffold projects following best practices

📋 Overview

The Payload CMS 3.0 MCP Server is a specialized Model Context Protocol server designed to enhance your Payload CMS development experience. It helps developers build better Payload CMS applications by providing code validation, template generation, and project scaffolding capabilities that follow best practices.

✨ Features

📚 Code Validation	🔍 Code Generation	🚀 Project Scaffolding
Validate Payload CMS code for collections, fields, globals, and config files with detailed feedback on syntax errors and best practices.	Generate code templates for collections, fields, globals, access control, hooks, endpoints, plugins, blocks, and migrations.	Scaffold entire Payload CMS projects with validated options for consistency and adherence to best practices.

🔧 Payload CMS 3.0 Capabilities

Validation Tools

validate - Validate code for collections, fields, globals, and config
query - Query validation rules and best practices
mcp_query - Execute SQL-like queries for Payload CMS structures

Code Generation

generate_template - Generate code templates for various components
generate_collection - Create complete collection definitions
generate_field - Generate field definitions with proper typing

Project Setup

scaffold_project - Create entire Payload CMS project structures
validate_scaffold_options - Ensure scaffold options follow best practices (used internally by scaffold_project)

📝 Detailed Tool Reference

Validation Tools

`validate`

Validates Payload CMS code for syntax and best practices.

Parameters:

code (string): The code to validate
fileType (enum): Type of file - "collection", "field", "global", or "config"

Example Prompt:

Can you validate this Payload CMS collection code?

```typescript
export const Posts = {
  slug: 'posts',
  fields: [
    {
      name: 'title',
      type: 'text',
      required: true,
    },
    {
      name: 'content',
      type: 'richText',
    }
  ],
  admin: {
    useAsTitle: 'title',
  }
}


#### `query`  
Queries validation rules and best practices for Payload CMS.

**Parameters:**  
- `query` (string): The query string  
- `fileType` (optional enum): Type of file - "collection", "field", "global", or "config"  

**Example Prompt:**

What are the best practices for implementing access control in Payload CMS collections?


#### `mcp_query`  
Executes SQL-like queries against Payload CMS structures.

**Parameters:**  
- `sql` (string): SQL-like query string  

**Example Prompt:**

Can you execute this query to find all valid field types in Payload CMS? SELECT field_types FROM payload_schema WHERE version = '3.0'


### Code Generation

#### `generate_template`  
Generates code templates for various Payload CMS components.

**Parameters:**  
- `templateType` (enum): Type of template - "collection", "field", "global", "config", "access-control", "hook", "endpoint", "plugin", "block", "migration"  
- `options` (record): Configuration options for the template  

**Example Prompt:**

Generate a template for a Payload CMS hook that logs when a document is created.


#### `generate_collection`  
Generates a complete Payload CMS collection definition.

**Parameters:**  
- `slug` (string): Collection slug  
- `fields` (optional array): Array of field objects  
- `auth` (optional boolean): Whether this is an auth collection  
- `timestamps` (optional boolean)  
- `admin` (optional object): Admin panel configuration  
- `hooks` (optional boolean)  
- `access` (optional boolean)  
- `versions` (optional boolean)  

**Example Prompt:**

Generate a Payload CMS collection for a blog with title, content, author, and published date fields. Include timestamps and versioning.


#### `generate_field`  
Generates a Payload CMS field definition.

**Parameters:**  
- `name` (string): Field name  
- `type` (string): Field type  
- `required` (optional boolean)  
- `unique` (optional boolean)  
- `localized` (optional boolean)  
- `access` (optional boolean)  
- `admin` (optional object)  
- `validation` (optional boolean)  
- `defaultValue` (optional any)  

**Example Prompt:**

Generate a Payload CMS image field with validation that requires alt text and has a description in the admin panel.


### Project Setup

#### `scaffold_project`  
Scaffolds a complete Payload CMS project structure.

**Parameters:**  
- `projectName` (string)  
- `description` (optional string)  
- `serverUrl` (optional string)  
- `database` (optional enum): "mongodb" or "postgres"  
- `auth` (optional boolean)  
- `admin` (optional object)  
- `collections` (optional array)  
- `globals` (optional array)  
- `blocks` (optional array)  
- `plugins` (optional array)  
- `typescript` (optional boolean)  

**Example Prompt:**

Scaffold a Payload CMS project called "blog-platform" with MongoDB, authentication, and collections for posts, categories, and users. Include a global for site settings.


---

## 🚀 Getting Started

### 1. Prerequisites

- Node.js 18+  
- An active Railway account  
- A Railway API token (create one at https://railway.app/account/tokens)  
- Basic familiarity with Payload CMS 3.0 concepts  

### 2. Configure Cursor

To use with Cursor IDE:

1. Open Cursor Settings  
2. Go to MCP Servers section  
3. Add a new MCP server  
4. Name it "Payload CMS 3.0 MCP"  
5. Set Transport Type to "Command"  
6. Set Command to: `railway run --service=YOUR_SERVICE_ID`  
7. Save the configuration  

### 3. Using the MCP Server

Common AI prompt uses:

- **Code Validation:** "Validate this Payload CMS collection code"  
- **Template Generation:** "Generate a template for a media collection"  
- **Query Rules:** "Query validation rules for access control"  
- **SQL-like Queries:** "Execute a query to find field types for collections"  

### 4. Example Workflow

1. Generate a collection template with specific fields  
2. Validate the generated code for best practices  
3. Query for specific validation rules to improve the code  
4. Generate additional components like hooks or endpoints  
5. Scaffold a complete project structure when ready  

### 5. Complete Workflow Example

User: I need to create a Payload CMS collection for a product catalog.

AI: I'll help you create a product catalog collection. Let me generate a template for you.

[Uses generate_collection tool]

Here's a collection template for your product catalog:

import { CollectionConfig } from 'payload/types';

export const Products: CollectionConfig = {
  slug: 'products',
  admin: {
    useAsTitle: 'name',
    defaultColumns: ['name', 'price', 'category', 'inStock'],
    group: 'Shop',
  },
  access: {
    read: () => true,
  },
  fields: [
    {
      name: 'name',
      type: 'text',
      required: true,
    },
    {
      name: 'description',
      type: 'richText',
    },
    {
      name: 'price',
      type: 'number',
      required: true,
    },
    {
      name: 'category',
      type: 'relationship',
      relationTo: 'categories',
      required: true,
    },
    {
      name: 'images',
      type: 'array',
      fields: [
        {
          name: 'image',
          type: 'upload',
          relationTo: 'media',
          required: true,
        },
        {
          name: 'altText',
          type: 'text',
          required: true,
        }
      ]
    },
    {
      name: 'inStock',
      type: 'checkbox',
      defaultValue: true,
    },
  ],
  timestamps: true,
}

User: Can you validate this code to make sure it follows best practices?

AI: I'll validate the code for you.

[Uses validate tool]

The validation results show that your code is valid and follows best practices. Here are a few suggestions:

Consider adding a maxDepth to your category relationship field to prevent deep queries
You might want to add access control for create, update, and delete operations
Consider adding hooks for inventory management when products are updated

User: What are the best practices for access control in Payload CMS?

AI: Let me query the validation rules for access control.

[Uses query tool]

Here are the best practices for access control in Payload CMS:

Always define explicit access control functions for create, read, update, and delete operations
Use role-based access control for admin users
Implement field-level access control for sensitive data
Use collection-level access control for broad permissions
Consider using hooks alongside access control for complex logic

User: Now I need to scaffold a complete project with this product collection and a categories collection.

AI: I'll scaffold a complete project for you.

[Uses scaffold_project tool]

I've generated a complete Payload CMS project structure with the following:

Product collection as you specified
Categories collection with name and description fields
Media collection for product images
Authentication for admin users
TypeScript configuration
MongoDB database setup
All necessary files and configurations

The project is ready to be initialized with npm install and npm run dev.


---

## 📋 Scaffolding Examples & Detailed Prompts

### Project Scaffolding Examples

Scaffolded project structure example:

e-commerce-platform/ ├── .env ├── .eslintrc.js ├── .gitignore ├── README.md ├── package.json ├── tsconfig.json ├── src/ │ ├── payload.config.ts │ ├── server.ts │ ├── collections/ │ │ ├── Products.ts │ │ ├── Categories.ts │ │ ├── Orders.ts │ │ ├── Customers.ts │ │ ├── Media.ts │ │ └── Users.ts │ ├── globals/ │ │ ├── Settings.ts │ │ └── Footer.ts │ ├── blocks/ │ │ ├── Hero.ts │ │ ├── ProductGrid.ts │ │ └── CallToAction.ts │ ├── fields/ │ │ ├── richText/ │ │ ├── metaImage.ts │ │ └── slug.ts │ ├── hooks/ │ │ ├── beforeChange.ts │ │ └── afterChange.ts │ ├── access/ │ │ ├── isAdmin.ts │ │ └── isAdminOrSelf.ts │ └── utilities/ │ ├── formatSlug.ts │ └── sendEmail.ts


### Example Scaffold Project Prompt (Basic)

Scaffold a Payload CMS project for a blog platform with the following:

Project name: blog-platform
Database: MongoDB
Authentication: Yes
Collections: Posts, Categories, Authors, Media
Globals: SiteSettings
TypeScript: Yes


### Example Scaffold Project Prompt (Detailed)

Scaffold a comprehensive Payload CMS project for an e-commerce platform with the following specifications:

Project details:

Name: luxury-watches-store
Description: "An e-commerce platform for luxury watches"
Database: PostgreSQL
TypeScript: Yes

Collections needed:

Products collection with:
- Name (text, required)
- Description (rich text)
- Price (number, required)
- SKU (text, unique)
- Brand (relationship to Brands collection)
- Categories (relationship to Categories, multiple)
- Features (array of text fields)
- Specifications (array of key-value pairs)
- Images (array of media uploads with alt text)
- Stock quantity (number)
- Status (select: available, out of stock, discontinued)
Categories collection with:
- Name (text, required)
- Description (rich text)
- Parent category (self-relationship)
- Image (media upload)
Brands collection with:
- Name (text, required)
- Logo (media upload)
- Description (rich text)
- Founded year (number)
- Country of origin (text)
Orders collection with:
- Order number (text, generated)
- Customer (relationship to Users)
- Products (array of relationships to Products with quantity)
- Status (select: pending, processing, shipped, delivered, cancelled)
- Shipping address (group of fields)
- Billing address (group of fields)
- Payment method (select)
- Total amount (number, calculated)
- Notes (text)
Users collection (auth enabled) with:
- Email (email, required)
- Name (text, required)
- Shipping addresses (array of address groups)
- Order history (relationship to Orders)
- Wishlist (relationship to Products)
- Role (select: customer, admin)

Globals:

SiteSettings with:
- Site name
- Logo
- Contact information
- Social media links
- SEO defaults
ShippingMethods with:
- Array of shipping options with prices

Include access control for:

Admin-only access to manage products, categories, brands
Customer access to their own orders and profile
Public read access to products and categories

Add hooks for:

Updating stock when orders are placed
Generating order numbers
Sending email notifications on order status changes


### Example Collection Creation Prompt (Basic)

Generate a Payload CMS collection for blog posts with title, content, author, and published date fields.


### Example Collection Creation Prompt (Detailed)

Generate a Payload CMS collection for a real estate property listing with the following specifications:

Collection name: Properties Admin configuration:

Use "title" as the display field
Group under "Listings" in the admin panel
Default columns: title, price, location, status, createdAt

Fields:

Title (text, required)
Slug (text, unique, generated from title)
Description (rich text with basic formatting options)
Price (number, required)
Location (group) with:
- Address (text)
- City (text, required)
- State/Province (text, required)
- Postal code (text)
- Country (select from predefined list)
- Coordinates (point) for map display
Property details (group) with:
- Property type (select: house, apartment, condo, land, commercial)
- Bedrooms (number)
- Bathrooms (number)
- Square footage (number)
- Lot size (number)
- Year built (number)
- Parking spaces (number)
Features (array of checkboxes) including:
- Air conditioning
- Swimming pool
- Garden
- Garage
- Fireplace
- Security system
- Elevator
- Furnished
Images (array of media uploads with alt text and caption)
Documents (array of file uploads for floor plans, certificates, etc.)
Status (select: available, under contract, sold, off market)
Featured (checkbox to highlight on homepage)
Agent (relationship to Users collection, required)
Related properties (relationship to self, multiple)

Access control:

Public read access
Agent can create and edit their own listings
Admin can manage all listings

Hooks:

Before change: Format slug from title
After change: Notify agent of status changes

Versioning: Enabled
Timestamps: Enabled


### Level of Detail in Prompts

The MCP server can handle prompts with varying levels of detail:

- **Minimal Detail (AI fills in the gaps):**  
  `Generate a collection for blog posts.`

- **Moderate Detail (Specific requirements):**  
  `Generate a collection for blog posts with title, content, featured image, categories, and author fields. Make title and content required.`

- **High Detail (Complete specifications):**

Generate a collection for blog posts with:

Slug: posts
Fields:
- Title (text, required)
- Content (rich text with custom formatting options)
- Featured image (upload with alt text)
- Categories (relationship to categories collection, multiple)
- Author (relationship to users collection)
- Status (select: draft, published, archived)
- Published date (date)
- SEO (group with title, description, and keywords)
Admin configuration:
- Use title as display field
- Group under "Content"
- Default columns: title, author, status, publishedDate
Access control for different user roles
Hooks for slug generation and notification
Enable versioning and timestamps


### Tips for Effective Prompts

1. Be specific about requirements  
2. Specify relationships between collections  
3. Include validation needs  
4. Describe admin UI preferences  
5. Mention hooks and access control requirements  
6. Use domain-specific terminology  

---

## 📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

## 🌍 About MATMAX WORLDWIDE

MATMAX WORLDWIDE  
Creating technology that helps humans be more human.

We believe in tech for good—tools that enhance our lives while respecting our humanity. Join us in building a future where technology serves wellness, connection, and purpose. Together, we can create digital experiences that bring out the best in us all.

Visit [matmax.world](https://matmax.world) to learn more about our vision for human-centered technology.

---

## 🖥️ Running Locally

You can run the Payload CMS MCP Server locally using npm:

### Option 1: Install from npm

```bash
# Install globally
npm install -g payload-cms-mcp

# Run the server
payload-cms-mcp

Option 2: Clone the repository

git clone https://github.com/Matmax-Worldwide/payloadcmsmcp.git
cd payloadcmsmcp
npm install
npm run dev

Alternatively:

npm run local

Your MCP server will now be running locally and accessible for development and testing without requiring a Railway API token.

🚀 Deployment Options

Deploy to Railway (Recommended)

The easiest way to deploy the MCP server is using Railway's one-click deployment:

After clicking the Deploy button on Railway:

Select "Deploy from GitHub repo"
Search for "Matmax-Worldwide/payloadcmsmcp"
Click "Deploy Now"

Quick Cursor IDE Setup

After deployment:

Install Railway CLI: npm install -g @railway/cli
Login to Railway: railway login
Link to your project: railway link
In Cursor Settings > MCP Servers, set Command to:
```
railway run
```