Payload MCP

> ⚠️ Work in Progress

> This repository is under active development and not yet feature-complete. APIs, configurations, and CLI commands may change without notice. Use at your own risk!

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
• Local-first: Run entirely on your local machine for privacy and security

Getting Started

Prerequisites

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

Installation

1. Install the package:

npm install -g @ngyngcphu/payload-mcp

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

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

3. The server will start automatically when needed by your MCP client. The default port is 3001.

Manual Start (Optional)

If you want to start the server manually:

npx @ngyngcphu/payload-mcp

Tool Reference

Payload MCP provides four categories of tools:

Generator Tools

Generate boilerplate code for Payload CMS components:

Query Tools

Tools for querying and analyzing your Payload CMS codebase:

Scaffold Tools

Tools for scaffolding new Payload CMS projects:

Validator Tools

Tools for validating your Payload CMS components:

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
};

// The AI would use the generate_template tool with these options
// Result would be a complete collection configuration file

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
};

// The AI would use the validate_query tool with this query
// Result would indicate if the query is valid and properly formatted

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"
};

// The AI would use the create_project tool with these options
// Result would be instructions for setting up a complete project

Configuration

Payload MCP can be configured by modifying the following files:

• `package.json`: Update the `name`, `version`, and other metadata
• `index.ts`: Change the default port (3001) if needed
• `server/index.ts`: Configure server options such as the MCP server name

Example Workflow

A typical workflow using Payload MCP might look like this:

1. Start the MCP Server:

npm start

2. Connect Your AI Assistant:

Configure your AI assistant to use the MCP server at `http://localhost:3001/`

3. Request Generation:

Ask your AI assistant to generate a new collection for your Payload CMS project

4. Review & Integrate:

Review the generated code and integrate it into your Payload CMS project

5. Validate:

Use the validation tools to ensure your implementation is correct

6. Iterate:

Continue developing with the help of your AI assistant and the MCP tools

Tips and Best Practices

• Start with Scaffolding: For new projects, use the scaffolding tools to set up a well-structured project
• Validate Frequently: Use the validation tools to catch issues early in your development process
• Combine Tools: Most complex tasks require multiple tools - for example, generating a collection and then validating it
• Review Generated Code: Always review generated code before integrating it into your project
• Keep the Server Running: Leave the MCP server running during your development session so your AI assistant can access it
• Use with Git: Commit your changes frequently so you can easily track and revert changes if needed

Future Plans

• Additional generators for more Payload CMS component types
• Integration with popular IDEs
• Support for GraphQL query generation and validation
• Performance optimizations for large Payload CMS projects

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.