Payload CMS 3.0 MCP Server
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
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:
`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:
`mcp_query`
Executes SQL-like queries against Payload CMS structures.
Parameters:
sql(string): SQL-like query string
Example Prompt:
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_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): Whether to include timestamps
admin(optional object): Admin panel configuration
hooks(optional boolean): Whether to include hooks
access(optional boolean): Whether to include access control
versions(optional boolean): Whether to enable versioning
Example Prompt:
`generate_field`
Generates a Payload CMS field definition.
Parameters:
name(string): Field name
type(string): Field type
required(optional boolean): Whether the field is required
unique(optional boolean): Whether the field should be unique
localized(optional boolean): Whether the field should be localized
access(optional boolean): Whether to include access control
admin(optional object): Admin panel configuration
validation(optional boolean): Whether to include validation
defaultValue(optional any): Default value for the field
Example Prompt:
Project Setup
`scaffold_project`
Scaffolds a complete Payload CMS project structure.
Parameters:
projectName(string): Name of the project
description(optional string): Project description
serverUrl(optional string): Server URL
database(optional enum): Database type - "mongodb" or "postgres"
auth(optional boolean): Whether to include authentication
admin(optional object): Admin panel configuration
collections(optional array): Array of collection objects
globals(optional array): Array of global objects
blocks(optional array): Array of block objects
plugins(optional array): Array of plugin strings
typescript(optional boolean): Whether to use TypeScript
Example Prompt:
Getting Started
1. Prerequisites
Before you begin, make sure you have:
- Node.js 18+ (required for Payload CMS 3.0)
- An active Railway account
- A Railway API token (create one at railway.app/account/tokens)
- Basic familiarity with Payload CMS 3.0 concepts
2. Configure Cursor
To use with Cursor IDE:
- Open Cursor Settings
- Go to MCP Servers section
- Add a new MCP server
- Name it "Payload CMS 3.0 MCP"
- Set Transport Type to "Command"
- Set Command to:
railway run --service=YOUR_SERVICE_ID
- Save the configuration
3. Using the MCP Server
Once configured, you can use these tools in your AI prompts:
- 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
A typical workflow with the Payload CMS MCP Server:
- Generate a collection template with specific fields
- Validate the generated code for best practices
- Query for specific validation rules to improve the code
- Generate additional components like hooks or endpoints
- Scaffold a complete project structure when ready
5. Complete Workflow Example
Here's a complete example of how you might use the MCP server in a conversation:
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
When you scaffold a project using the MCP server, you'll receive a complete project structure. Here's what a scaffolded e-commerce project might look like:
Example Scaffold Project Prompt (Basic)
Example Scaffold Project Prompt (Detailed)
Note: Code block was split into 2 parts due to size limits.
Example Collection Creation Prompt (Basic)
Example Collection Creation Prompt (Detailed)
Level of Detail in Prompts
The MCP server can handle prompts with varying levels of detail:
Minimal Detail (AI fills in the gaps)
Moderate Detail (Specific requirements)
High Detail (Complete specifications)
Tips for Effective Prompts
- Be specific about requirements: The more details you provide, the more tailored the output will be.
- Specify relationships: Clearly indicate how collections relate to each other.
- Include validation needs: Mention any validation rules or constraints for fields.
- Describe admin UI preferences: Specify how you want the collection to appear in the admin panel.
- Mention hooks and access control: If you need specific business logic or security rules, include them in your prompt.
- Use domain-specific terminology: Describe your project using terms relevant to your industry or use case.
License
This project is licensed under the MIT License - see the LICENSE file for details.
About MATMAX WORLDWIDE
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 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
Option 2: Clone the repository
- Clone the repository:
- Install dependencies:
- Run the server locally:
Or alternatively:
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 button:
- 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
Payload CMS 3.0 MCP Server
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
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:
`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:
`mcp_query`
Executes SQL-like queries against Payload CMS structures.
Parameters:
sql(string): SQL-like query string
Example Prompt:
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_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): Whether to include timestamps
admin(optional object): Admin panel configuration
hooks(optional boolean): Whether to include hooks
access(optional boolean): Whether to include access control
versions(optional boolean): Whether to enable versioning
Example Prompt:
`generate_field`
Generates a Payload CMS field definition.
Parameters:
name(string): Field name
type(string): Field type
required(optional boolean): Whether the field is required
unique(optional boolean): Whether the field should be unique
localized(optional boolean): Whether the field should be localized
access(optional boolean): Whether to include access control
admin(optional object): Admin panel configuration
validation(optional boolean): Whether to include validation
defaultValue(optional any): Default value for the field
Example Prompt:
Project Setup
`scaffold_project`
Scaffolds a complete Payload CMS project structure.
Parameters:
projectName(string): Name of the project
description(optional string): Project description
serverUrl(optional string): Server URL
database(optional enum): Database type - "mongodb" or "postgres"
auth(optional boolean): Whether to include authentication
admin(optional object): Admin panel configuration
collections(optional array): Array of collection objects
globals(optional array): Array of global objects
blocks(optional array): Array of block objects
plugins(optional array): Array of plugin strings
typescript(optional boolean): Whether to use TypeScript
Example Prompt:
Getting Started
1. Prerequisites
Before you begin, make sure you have:
- Node.js 18+ (required for Payload CMS 3.0)
- An active Railway account
- A Railway API token (create one at railway.app/account/tokens)
- Basic familiarity with Payload CMS 3.0 concepts
2. Configure Cursor
To use with Cursor IDE:
- Open Cursor Settings
- Go to MCP Servers section
- Add a new MCP server
- Name it "Payload CMS 3.0 MCP"
- Set Transport Type to "Command"
- Set Command to:
railway run --service=YOUR_SERVICE_ID
- Save the configuration
3. Using the MCP Server
Once configured, you can use these tools in your AI prompts:
- 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
A typical workflow with the Payload CMS MCP Server:
- Generate a collection template with specific fields
- Validate the generated code for best practices
- Query for specific validation rules to improve the code
- Generate additional components like hooks or endpoints
- Scaffold a complete project structure when ready
5. Complete Workflow Example
Here's a complete example of how you might use the MCP server in a conversation:
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
When you scaffold a project using the MCP server, you'll receive a complete project structure. Here's what a scaffolded e-commerce project might look like:
Example Scaffold Project Prompt (Basic)
Example Scaffold Project Prompt (Detailed)
Note: Code block was split into 2 parts due to size limits.
Example Collection Creation Prompt (Basic)
Example Collection Creation Prompt (Detailed)
Level of Detail in Prompts
The MCP server can handle prompts with varying levels of detail:
Minimal Detail (AI fills in the gaps)
Moderate Detail (Specific requirements)
High Detail (Complete specifications)
Tips for Effective Prompts
- Be specific about requirements: The more details you provide, the more tailored the output will be.
- Specify relationships: Clearly indicate how collections relate to each other.
- Include validation needs: Mention any validation rules or constraints for fields.
- Describe admin UI preferences: Specify how you want the collection to appear in the admin panel.
- Mention hooks and access control: If you need specific business logic or security rules, include them in your prompt.
- Use domain-specific terminology: Describe your project using terms relevant to your industry or use case.
License
This project is licensed under the MIT License - see the LICENSE file for details.
About MATMAX WORLDWIDE
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 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
Option 2: Clone the repository
- Clone the repository:
- Install dependencies:
- Run the server locally:
Or alternatively:
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 button:
- 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