Skip to content
Back to search

payloadcmsmcp

Payload CMS MCP Server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/disruption-hub--payloadcmsmcp/badge.svg)](/listings/disruption-hub--payloadcmsmcp)

HTML

<a href="/listings/disruption-hub--payloadcmsmcp"><img src="/api/listings/disruption-hub--payloadcmsmcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

<hr>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 707 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # 🚀 Payload CMS 3.0 MCP Server
  2. <div align="center">
  3. <p align="center">
  4. <img src="https://www.payloadcmsmcp.info/logopayload.png" alt="Payload CMS Logo" width="120" height="120" style="border-radius: 10px; padding: 5px; background-color: white; box-shadow: 0 3px 10px rgba(0, 0, 0, 0.25);" />
  5. </p>
  6. <p align="center">
  7. <img src="https://img.shields.io/badge/Model%20Context%20Protocol-Enabled-6366F1?style=for-the-badge" alt="MCP Enabled" />
  8. <img src="https://img.shields.io/badge/Payload%20CMS%203.0-Integration-3B82F6?style=for-the-badge" alt="Payload CMS" />
  9. <img src="https://img.shields.io/badge/License-MIT-10B981?style=for-the-badge" alt="License" />
  10. <img src="https://img.shields.io/badge/Railway-Deployment-0B0D0E?style=for-the-badge" alt="Railway Deployment" />
  11. </p>
  12. <h3>A specialized MCP server for Payload CMS 3.0</h3>
  13. <p>Validate code, generate templates, and scaffold projects following best practices</p>
  14. </div>
  15. <hr>
  16. ## 📋 Overview
  17. 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.
  18. <hr>
  19. ## ✨ Features
  20. <div align="center">
  21. <table>
  22. <tr>
  23. <td align="center">
  24. <h3>📚</h3>
  25. <b>Code Validation</b>
  26. <p>Validate Payload CMS code for collections, fields, globals, and config files with detailed feedback on syntax errors and best practices.</p>
  27. </td>
  28. <td align="center">
  29. <h3>🔍</h3>
  30. <b>Code Generation</b>
  31. <p>Generate code templates for collections, fields, globals, access control, hooks, endpoints, plugins, blocks, and migrations.</p>
  32. </td>
  33. <td align="center">
  34. <h3>🚀</h3>
  35. <b>Project Scaffolding</b>
  36. <p>Scaffold entire Payload CMS projects with validated options for consistency and adherence to best practices.</p>
  37. </td>
  38. </tr>
  39. </table>
  40. </div>
  41. <hr>
  42. ## 🔧 Payload CMS 3.0 Capabilities
  43. ### Validation Tools
  44. * `validate` - Validate code for collections, fields, globals, and config
  45. * `query` - Query validation rules and best practices
  46. * `mcp_query` - Execute SQL-like queries for Payload CMS structures
  47. ### Code Generation
  48. * `generate_template` - Generate code templates for various components
  49. * `generate_collection` - Create complete collection definitions
  50. * `generate_field` - Generate field definitions with proper typing
  51. ### Project Setup
  52. * `scaffold_project` - Create entire Payload CMS project structures
  53. * `validate_scaffold_options` - Ensure scaffold options follow best practices (used internally by scaffold_project)
  54. <hr>
  55. ## 📝 Detailed Tool Reference
  56. ### Validation Tools
  57. #### `validate`
  58. Validates Payload CMS code for syntax and best practices.
  59. **Parameters:**
  60. - `code` (string): The code to validate
  61. - `fileType` (enum): Type of file - "collection", "field", "global", or "config"
  62. **Example Prompt:**
  63. ```
  64. Can you validate this Payload CMS collection code?
  65. ```typescript
  66. export const Posts = {
  67. slug: 'posts',
  68. fields: [
  69. {
  70. name: 'title',
  71. type: 'text',
  72. required: true,
  73. },
  74. {
  75. name: 'content',
  76. type: 'richText',
  77. }
  78. ],
  79. admin: {
  80. useAsTitle: 'title',
  81. }
  82. }
  83. ```
  84. #### `query`
  85. Queries validation rules and best practices for Payload CMS.
  86. **Parameters:**
  87. - `query` (string): The query string
  88. - `fileType` (optional enum): Type of file - "collection", "field", "global", or "config"
  89. **Example Prompt:**
  90. ```
  91. What are the best practices for implementing access control in Payload CMS collections?
  92. ```
  93. #### `mcp_query`
  94. Executes SQL-like queries against Payload CMS structures.
  95. **Parameters:**
  96. - `sql` (string): SQL-like query string
  97. **Example Prompt:**
  98. ```
  99. Can you execute this query to find all valid field types in Payload CMS?
  100. SELECT field_types FROM payload_schema WHERE version = '3.0'
  101. ```
  102. ### Code Generation
  103. #### `generate_template`
  104. Generates code templates for various Payload CMS components.
  105. **Parameters:**
  106. - `templateType` (enum): Type of template - "collection", "field", "global", "config", "access-control", "hook", "endpoint", "plugin", "block", "migration"
  107. - `options` (record): Configuration options for the template
  108. **Example Prompt:**
  109. ```
  110. Generate a template for a Payload CMS hook that logs when a document is created.
  111. ```
  112. #### `generate_collection`
  113. Generates a complete Payload CMS collection definition.
  114. **Parameters:**
  115. - `slug` (string): Collection slug
  116. - `fields` (optional array): Array of field objects
  117. - `auth` (optional boolean): Whether this is an auth collection
  118. - `timestamps` (optional boolean): Whether to include timestamps
  119. - `admin` (optional object): Admin panel configuration
  120. - `hooks` (optional boolean): Whether to include hooks
  121. - `access` (optional boolean): Whether to include access control
  122. - `versions` (optional boolean): Whether to enable versioning
  123. **Example Prompt:**
  124. ```
  125. Generate a Payload CMS collection for a blog with title, content, author, and published date fields. Include timestamps and versioning.
  126. ```
  127. #### `generate_field`
  128. Generates a Payload CMS field definition.
  129. **Parameters:**
  130. - `name` (string): Field name
  131. - `type` (string): Field type
  132. - `required` (optional boolean): Whether the field is required
  133. - `unique` (optional boolean): Whether the field should be unique
  134. - `localized` (optional boolean): Whether the field should be localized
  135. - `access` (optional boolean): Whether to include access control
  136. - `admin` (optional object): Admin panel configuration
  137. - `validation` (optional boolean): Whether to include validation
  138. - `defaultValue` (optional any): Default value for the field
  139. **Example Prompt:**
  140. ```
  141. Generate a Payload CMS image field with validation that requires alt text and has a description in the admin panel.
  142. ```
  143. ### Project Setup
  144. #### `scaffold_project`
  145. Scaffolds a complete Payload CMS project structure.
  146. **Parameters:**
  147. - `projectName` (string): Name of the project
  148. - `description` (optional string): Project description
  149. - `serverUrl` (optional string): Server URL
  150. - `database` (optional enum): Database type - "mongodb" or "postgres"
  151. - `auth` (optional boolean): Whether to include authentication
  152. - `admin` (optional object): Admin panel configuration
  153. - `collections` (optional array): Array of collection objects
  154. - `globals` (optional array): Array of global objects
  155. - `blocks` (optional array): Array of block objects
  156. - `plugins` (optional array): Array of plugin strings
  157. - `typescript` (optional boolean): Whether to use TypeScript
  158. **Example Prompt:**
  159. ```
  160. Scaffold a Payload CMS project called "blog-platform" with MongoDB, authentication, and collections for posts, categories, and users. Include a global for site settings.
  161. ```
  162. <hr>
  163. ## 🚀 Getting Started
  164. ### 1. Prerequisites
  165. Before you begin, make sure you have:
  166. * Node.js 18+ (required for Payload CMS 3.0)
  167. * An active Railway account
  168. * A Railway API token (create one at [railway.app/account/tokens](https://railway.app/account/tokens))
  169. * Basic familiarity with Payload CMS 3.0 concepts
  170. ### 2. Configure Cursor
  171. To use with Cursor IDE:
  172. 1. Open Cursor Settings
  173. 2. Go to MCP Servers section
  174. 3. Add a new MCP server
  175. 4. Name it "Payload CMS 3.0 MCP"
  176. 5. Set Transport Type to "Command"
  177. 6. Set Command to: `railway run --service=YOUR_SERVICE_ID`
  178. 7. Save the configuration
  179. ### 3. Using the MCP Server
  180. Once configured, you can use these tools in your AI prompts:
  181. * **Code Validation:** "Validate this Payload CMS collection code"
  182. * **Template Generation:** "Generate a template for a media collection"
  183. * **Query Rules:** "Query validation rules for access control"
  184. * **SQL-like Queries:** "Execute a query to find field types for collections"
  185. ### 4. Example Workflow
  186. A typical workflow with the Payload CMS MCP Server:
  187. 1. Generate a collection template with specific fields
  188. 2. Validate the generated code for best practices
  189. 3. Query for specific validation rules to improve the code
  190. 4. Generate additional components like hooks or endpoints
  191. 5. Scaffold a complete project structure when ready
  192. ### 5. Complete Workflow Example
  193. Here's a complete example of how you might use the MCP server in a conversation:
  194. ```
  195. User: I need to create a Payload CMS collection for a product catalog.
  196. AI: I'll help you create a product catalog collection. Let me generate a template for you.
  197. [Uses generate_collection tool]
  198. Here's a collection template for your product catalog:
  199. ```typescript
  200. import { CollectionConfig } from 'payload/types';
  201. export const Products: CollectionConfig = {
  202. slug: 'products',
  203. admin: {
  204. useAsTitle: 'name',
  205. defaultColumns: ['name', 'price', 'category', 'inStock'],
  206. group: 'Shop',
  207. },
  208. access: {
  209. read: () => true,
  210. },
  211. fields: [
  212. {
  213. name: 'name',
  214. type: 'text',
  215. required: true,
  216. },
  217. {
  218. name: 'description',
  219. type: 'richText',
  220. },
  221. {
  222. name: 'price',
  223. type: 'number',
  224. required: true,
  225. },
  226. {
  227. name: 'category',
  228. type: 'relationship',
  229. relationTo: 'categories',
  230. required: true,
  231. },
  232. {
  233. name: 'images',
  234. type: 'array',
  235. fields: [
  236. {
  237. name: 'image',
  238. type: 'upload',
  239. relationTo: 'media',
  240. required: true,
  241. },
  242. {
  243. name: 'altText',
  244. type: 'text',
  245. required: true,
  246. }
  247. ]
  248. },
  249. {
  250. name: 'inStock',
  251. type: 'checkbox',
  252. defaultValue: true,
  253. },
  254. ],
  255. timestamps: true,
  256. }
  257. ```
  258. User: Can you validate this code to make sure it follows best practices?
  259. AI: I'll validate the code for you.
  260. [Uses validate tool]
  261. The validation results show that your code is valid and follows best practices. Here are a few suggestions:
  262. 1. Consider adding a maxDepth to your category relationship field to prevent deep queries
  263. 2. You might want to add access control for create, update, and delete operations
  264. 3. Consider adding hooks for inventory management when products are updated
  265. User: What are the best practices for access control in Payload CMS?
  266. AI: Let me query the validation rules for access control.
  267. [Uses query tool]
  268. Here are the best practices for access control in Payload CMS:
  269. 1. Always define explicit access control functions for create, read, update, and delete operations
  270. 2. Use role-based access control for admin users
  271. 3. Implement field-level access control for sensitive data
  272. 4. Use collection-level access control for broad permissions
  273. 5. Consider using hooks alongside access control for complex logic
  274. User: Now I need to scaffold a complete project with this product collection and a categories collection.
  275. AI: I'll scaffold a complete project for you.
  276. [Uses scaffold_project tool]
  277. I've generated a complete Payload CMS project structure with the following:
  278. - Product collection as you specified
  279. - Categories collection with name and description fields
  280. - Media collection for product images
  281. - Authentication for admin users
  282. - TypeScript configuration
  283. - MongoDB database setup
  284. - All necessary files and configurations
  285. The project is ready to be initialized with `npm install` and `npm run dev`.
  286. <hr>
  287. ## 📋 Scaffolding Examples & Detailed Prompts
  288. ### Project Scaffolding Examples
  289. 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:
  290. ```
  291. e-commerce-platform/
  292. ├── .env
  293. ├── .eslintrc.js
  294. ├── .gitignore
  295. ├── README.md
  296. ├── package.json
  297. ├── tsconfig.json
  298. ├── src/
  299. │ ├── payload.config.ts
  300. │ ├── server.ts
  301. │ ├── collections/
  302. │ │ ├── Products.ts
  303. │ │ ├── Categories.ts
  304. │ │ ├── Orders.ts
  305. │ │ ├── Customers.ts
  306. │ │ ├── Media.ts
  307. │ │ └── Users.ts
  308. │ ├── globals/
  309. │ │ ├── Settings.ts
  310. │ │ └── Footer.ts
  311. │ ├── blocks/
  312. │ │ ├── Hero.ts
  313. │ │ ├── ProductGrid.ts
  314. │ │ └── CallToAction.ts
  315. │ ├── fields/
  316. │ │ ├── richText/
  317. │ │ ├── metaImage.ts
  318. │ │ └── slug.ts
  319. │ ├── hooks/
  320. │ │ ├── beforeChange.ts
  321. │ │ └── afterChange.ts
  322. │ ├── access/
  323. │ │ ├── isAdmin.ts
  324. │ │ └── isAdminOrSelf.ts
  325. │ └── utilities/
  326. │ ├── formatSlug.ts
  327. │ └── sendEmail.ts
  328. ```
  329. ### Example Scaffold Project Prompt (Basic)
  330. ```
  331. Scaffold a Payload CMS project for a blog platform with the following:
  332. - Project name: blog-platform
  333. - Database: MongoDB
  334. - Authentication: Yes
  335. - Collections: Posts, Categories, Authors, Media
  336. - Globals: SiteSettings
  337. - TypeScript: Yes
  338. ```
  339. ### Example Scaffold Project Prompt (Detailed)
  340. ```
  341. Scaffold a comprehensive Payload CMS project for an e-commerce platform with the following specifications:
  342. Project details:
  343. - Name: luxury-watches-store
  344. - Description: "An e-commerce platform for luxury watches"
  345. - Database: PostgreSQL
  346. - TypeScript: Yes
  347. Collections needed:
  348. 1. Products collection with:
  349. - Name (text, required)
  350. - Description (rich text)
  351. - Price (number, required)
  352. - SKU (text, unique)
  353. - Brand (relationship to Brands collection)
  354. - Categories (relationship to Categories, multiple)
  355. - Features (array of text fields)
  356. - Specifications (array of key-value pairs)
  357. - Images (array of media uploads with alt text)
  358. - Stock quantity (number)
  359. - Status (select: available, out of stock, discontinued)
  360. 2. Categories collection with:
  361. - Name (text, required)
  362. - Description (rich text)
  363. - Parent category (self-relationship)
  364. - Image (media upload)
  365. 3. Brands collection with:
  366. - Name (text, required)
  367. - Logo (media upload)
  368. - Description (rich text)
  369. - Founded year (number)
  370. - Country of origin (text)
  371. 4. Orders collection with:
  372. - Order number (text, generated)
  373. - Customer (relationship to Users)
  374. - Products (array of relationships to Products with quantity)
  375. - Status (select: pending, processing, shipped, delivered, cancelled)
  376. - Shipping address (group of fields)
  377. - Billing address (group of fields)
  378. - Payment method (select)
  379. - Total amount (number, calculated)
  380. - Notes (text)
  381. 5. Users collection (auth enabled) with:
  382. - Email (email, required)
  383. - Name (text, required)
  384. - Shipping addresses (array of address groups)
  385. - Order history (relationship to Orders)
  386. - Wishlist (relationship to Products)
  387. - Role (select: customer, admin)
  388. Globals:
  389. 1. SiteSettings with:
  390. - Site name
  391. - Logo
  392. - Contact information
  393. - Social media links
  394. - SEO defaults
  395. 2. ShippingMethods with:
  396. - Array of shipping options with prices
  397. Include access control for:
  398. - Admin-only access to manage products, categories, brands
  399. - Customer access to their own orders and profile
  400. - Public read access to products and categories
  401. Add hooks for:
  402. - Updating stock when orders are placed
  403. - Generating order numbers
  404. - Sending email notifications on order status changes
  405. ```
  406. ### Example Collection Creation Prompt (Basic)
  407. ```
  408. Generate a Payload CMS collection for blog posts with title, content, author, and published date fields.
  409. ```
  410. ### Example Collection Creation Prompt (Detailed)
  411. ```
  412. Generate a Payload CMS collection for a real estate property listing with the following specifications:
  413. Collection name: Properties
  414. Admin configuration:
  415. - Use "title" as the display field
  416. - Group under "Listings" in the admin panel
  417. - Default columns: title, price, location, status, createdAt
  418. Fields:
  419. 1. Title (text, required)
  420. 2. Slug (text, unique, generated from title)
  421. 3. Description (rich text with basic formatting options)
  422. 4. Price (number, required)
  423. 5. Location (group) with:
  424. - Address (text)
  425. - City (text, required)
  426. - State/Province (text, required)
  427. - Postal code (text)
  428. - Country (select from predefined list)
  429. - Coordinates (point) for map display
  430. 6. Property details (group) with:
  431. - Property type (select: house, apartment, condo, land, commercial)
  432. - Bedrooms (number)
  433. - Bathrooms (number)
  434. - Square footage (number)
  435. - Lot size (number)
  436. - Year built (number)
  437. - Parking spaces (number)
  438. 7. Features (array of checkboxes) including:
  439. - Air conditioning
  440. - Swimming pool
  441. - Garden
  442. - Garage
  443. - Fireplace
  444. - Security system
  445. - Elevator
  446. - Furnished
  447. 8. Images (array of media uploads with alt text and caption)
  448. 9. Documents (array of file uploads for floor plans, certificates, etc.)
  449. 10. Status (select: available, under contract, sold, off market)
  450. 11. Featured (checkbox to highlight on homepage)
  451. 12. Agent (relationship to Users collection, required)
  452. 13. Related properties (relationship to self, multiple)
  453. Access control:
  454. - Public read access
  455. - Agent can create and edit their own listings
  456. - Admin can manage all listings
  457. Hooks:
  458. - Before change: Format slug from title
  459. - After change: Notify agent of status changes
  460. Versioning: Enabled
  461. Timestamps: Enabled
  462. ```
  463. ### Level of Detail in Prompts
  464. The MCP server can handle prompts with varying levels of detail:
  465. #### Minimal Detail (AI fills in the gaps)
  466. ```
  467. Generate a collection for blog posts.
  468. ```
  469. #### Moderate Detail (Specific requirements)
  470. ```
  471. Generate a collection for blog posts with title, content, featured image, categories, and author fields. Make title and content required.
  472. ```
  473. #### High Detail (Complete specifications)
  474. ```
  475. Generate a collection for blog posts with:
  476. - Slug: posts
  477. - Fields:
  478. - Title (text, required)
  479. - Content (rich text with custom formatting options)
  480. - Featured image (upload with alt text)
  481. - Categories (relationship to categories collection, multiple)
  482. - Author (relationship to users collection)
  483. - Status (select: draft, published, archived)
  484. - Published date (date)
  485. - SEO (group with title, description, and keywords)
  486. - Admin configuration:
  487. - Use title as display field
  488. - Group under "Content"
  489. - Default columns: title, author, status, publishedDate
  490. - Access control for different user roles
  491. - Hooks for slug generation and notification
  492. - Enable versioning and timestamps
  493. ```
  494. ### Tips for Effective Prompts
  495. 1. **Be specific about requirements**: The more details you provide, the more tailored the output will be.
  496. 2. **Specify relationships**: Clearly indicate how collections relate to each other.
  497. 3. **Include validation needs**: Mention any validation rules or constraints for fields.
  498. 4. **Describe admin UI preferences**: Specify how you want the collection to appear in the admin panel.
  499. 5. **Mention hooks and access control**: If you need specific business logic or security rules, include them in your prompt.
  500. 6. **Use domain-specific terminology**: Describe your project using terms relevant to your industry or use case.
  501. <hr>
  502. ## 📄 License
  503. This project is licensed under the MIT License - see the LICENSE file for details.
  504. <hr>
  505. ## 🌍 About MATMAX WORLDWIDE
  506. <div align="center">
  507. <h3>MATMAX WORLDWIDE</h3>
  508. <p>Creating technology that helps humans be more human.</p>
  509. </div>
  510. We believe in tech for good—tools that enhance our lives while respecting our humanity.
  511. 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.
  512. Visit [matmax.world](https://matmax.world) to learn more about our vision for human-centered technology.
  513. <hr>
  514. ## 🖥️ Running Locally
  515. You can run the Payload CMS MCP Server locally using npm:
  516. [![npm version](https://img.shields.io/npm/v/payload-cms-mcp.svg?style=flat-square)](https://www.npmjs.org/package/payload-cms-mcp)
  517. [![npm downloads](https://img.shields.io/npm/dm/payload-cms-mcp.svg?style=flat-square)](https://npmjs.org/package/payload-cms-mcp)
  518. ### Option 1: Install from npm
  519. ```bash
  520. # Install globally
  521. npm install -g payload-cms-mcp
  522. # Run the server
  523. payload-cms-mcp
  524. ```
  525. ### Option 2: Clone the repository
  526. 1. Clone the repository:
  527. ```bash
  528. git clone https://github.com/Matmax-Worldwide/payloadcmsmcp.git
  529. cd payloadcmsmcp
  530. ```
  531. 2. Install dependencies:
  532. ```bash
  533. npm install
  534. ```
  535. 3. Run the server locally:
  536. ```bash
  537. npm run dev
  538. ```
  539. Or alternatively:
  540. ```bash
  541. npm run local
  542. ```
  543. Your MCP server will now be running locally and accessible for development and testing without requiring a Railway API token.
  544. ## 🚀 Deployment Options
  545. ### Deploy to Railway (Recommended)
  546. The easiest way to deploy the MCP server is using Railway's one-click deployment:
  547. [![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/new)
  548. After clicking the button:
  549. 1. Select "Deploy from GitHub repo"
  550. 2. Search for "Matmax-Worldwide/payloadcmsmcp"
  551. 3. Click "Deploy Now"
  552. #### Quick Cursor IDE Setup
  553. After deployment:
  554. 1. Install Railway CLI: `npm install -g @railway/cli`
  555. 2. Login to Railway: `railway login`
  556. 3. Link to your project: `railway link`
  557. 4. In Cursor Settings > MCP Servers, set Command to: `railway run`

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.