Payload MCP

A powerful Model Context Protocol (MCP) server for Payload CMS that enables AI assistants to help you develop, manage, and extend your Payload CMS projects.

Overview

Payload MCP (Model Context Protocol) is a specialized server that connects AI assistants to your Payload CMS development workflow. It provides a set of tools for generating code, validating components, scaffolding projects, and performing specialized queries - all accessible to AI agents through the standardized Model Context Protocol.

This project implements an MCP server that can be run locally to provide AI assistants with capabilities specifically tailored for Payload CMS development, making it easier to:

• Generate boilerplate code for collections, fields, access control, and more
• Validate your Payload CMS components
• Scaffold new Payload CMS projects
• Query and analyze your existing codebase

Features

• Code Generation: Create collections, fields, config files, access control rules, hooks, endpoints, plugins, blocks, migrations, and components with the right structure and best practices
• Validation: Validate your Payload CMS components to ensure they follow best practices and will work correctly
• Scaffolding: Set up new Payload CMS projects with the right file structure and dependencies
• Specialized Queries: Get recommendations and insights for your Payload CMS codebase
• MCP Compliant: Works with any AI assistant that supports the Model Context Protocol
• Zero Configuration: No setup required - works out of the box with npx
• Stdio Transport: Uses standard input/output for efficient MCP communication
• TypeScript & Node.js/Bun: Full TypeScript support with both Node.js and Bun compatibility

Getting Started

Prerequisites

• Node.js (v16 or higher)
• npm or Bun (recommended)

Installation & Setup

No installation required! The package runs directly via npx.

1. Configure your MCP client (e.g., Cursor) by adding this to your mcp.json:

   {
     "mcpServers": {
       "@cura-digital/payload-mcp": {
         "command": "npx",
         "args": ["-y", "@cura-digital/payload-mcp"]
       }
     }
   }

2. That's it! The server will start automatically when your MCP client needs it.

Alternative: Manual Start

You can also run the server manually for testing:

# Using npx (recommended)
npx -y @cura-digital/payload-mcp

# Using bun
bun x @cura-digital/payload-mcp

# Or install globally first
npm install -g @cura-digital/payload-mcp
@cura-digital/payload-mcp

Tool Reference

Payload MCP provides four categories of tools:

Generator Tools

Generate boilerplate code for Payload CMS components:

| Tool | Description | |------|-------------| | generate_template | Generate any Payload CMS component (collections, fields, configs, access control, hooks, endpoints, plugins, blocks, migrations, components) |

Query Tools

Tools for querying and analyzing your Payload CMS codebase:

| Tool | Description | |------|-------------| | process_query | Validate Payload queries and get suggestions based on your collections |

Scaffold Tools

Tools for scaffolding new Payload CMS projects:

| Tool | Description | |------|-------------| | scaffold_project | Create a complete Payload CMS project with recommended structure, authentication, and deployment configurations |

Validator Tools

Tools for validating your Payload CMS components:

| Tool | Description | |------|-------------| | validate_code | Validate any Payload CMS component code (collections, fields, globals, configs) with syntax, best practices, security, and performance checks |

Example Usage

Generating a Collection

// Example: Generate a simple blog post collection
const options = {
  name: "Post",
  slug: "posts",
  fields: [
    { name: "title", type: "text", required: true },
    { name: "content", type: "richText" },
    { name: "status", type: "select", options: ["draft", "published"] }
  ],
  timestamps: true,
  auth: false
};

// AI assistants use the generate_template tool with type "collection" and these options
// Result: Complete TypeScript collection configuration ready to use

Validating a Query

// Example: Validate a query for the posts collection
const query = {
  where: {
    status: {
      equals: "published"
    },
    createdAt: {
      greater_than: "2023-01-01"
    }
  },
  sort: "-createdAt",
  limit: 10
};

// AI assistants use the process_query tool with this query
// Result: Validation status, suggestions, and formatted query

Scaffolding a New Project

// Example: Create a new Payload CMS project for a blog
const options = {
  name: "My Blog",
  collections: ["posts", "categories", "authors"],
  authentication: true,
  admin: {
    customization: true
  },
  database: "mongodb"
};

// AI assistants use the scaffold_project tool with these options
// Result: Complete project structure with files, dependencies, and setup instructions

How It Works

Payload MCP uses the Model Context Protocol (MCP) to communicate with AI assistants:

1. Stdio Transport: Uses standard input/output for efficient communication
2. Tool Registration: Automatically registers all available tools when started
3. Type Safety: Full TypeScript support with Zod schema validation
4. Zero Config: Works out of the box with no configuration needed

Example Workflow

A typical workflow using Payload MCP:

1. Configure MCP Client: Add the configuration to your MCP client (like Cursor)

2. Ask AI Assistant: "Generate a blog collection with title, content, and publish date fields"

3. Generate Code: AI assistant uses generate_template tool to create the collection

4. Scaffold Project: "Create a complete blog project with authentication"

5. Validate & Optimize: AI assistant uses validate_code to ensure best practices

6. Continue Development: Keep iterating with AI assistance for hooks, endpoints, and components

Tips and Best Practices

• Start with Scaffolding: Use scaffold_project to create well-structured projects
• Validate Early: Use validate_code to catch issues during development
• Combine Tools: Generate components with generate_template, then validate and refine
• Review Generated Code: Always review AI-generated code before integration
• Use Descriptive Prompts: Be specific about requirements for better code generation
• Version Control: Use Git to track changes and iterations

Supported MCP Clients

• Cursor: Add configuration to mcp.json
• Claude Desktop: Compatible with MCP protocol
• Any MCP Client: Works with any tool supporting MCP stdio transport

Development

# Clone and setup
git clone https://github.com/cura-digital/payload-mcp.git
cd payload-mcp
npm install

# Start development server
npm run dev
# or with bun
bun run bun:dev

# Build for production
npm run build

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

If you encounter any issues or have questions, please file an issue on the GitHub repository.