@govcraft/payload-cms-mcp

Payload CMS MCP

A Model Context Protocol (MCP) server for Payload CMS 3.0 that auto-generates tools from Payload's TypeScript type definitions. This server runs in stdio-only mode, making it compatible with MCP clients like Cursor.

Features

• Auto-generates MCP tools from Payload CMS 3.0 TypeScript definitions
• Provides AI assistants with up-to-date code generation capabilities for Payload CMS
• Runs in stdio-only mode for integration with MCP clients (no HTTP endpoint)
• Supports all major Payload CMS features:
  • Collections
  • Globals
  • Fields (all field types)
  • Hooks
  • Authentication
  • Configuration

How It Works

1. Parse Type Definitions: Uses ts-morph to analyze Payload's .d.ts files
2. Generate Tools: Converts types into MCP tools with parameters
3. Register Tools: Makes tools available via the MCP protocol
4. Generate Code: Returns properly formatted Payload CMS 3.0 code when tools are invoked

Getting Started

Prerequisites

• Node.js (v18 or higher)
• pnpm (v8 or higher) or npm

Installation

Option 1: From npm (recommended)

# Install globally
npm install -g @govcraft/payload-cms-mcp

# Or install locally in your project
npm install @govcraft/payload-cms-mcp

After installation, you can run the server using:

# If installed globally
payload-cms-mcp

# Using npx directly (preferred)
npx @govcraft/payload-cms-mcp

# Using pnpx (alternative option)
pnpx @govcraft/payload-cms-mcp

# Or run via npm scripts if installed locally in a project
npm run payload-cms-mcp

Option 2: From source

# Clone the repository
git clone https://github.com/Govcraft/payload-cms-mcp.git
cd payload-cms-mcp

# Install dependencies
pnpm install

# Start the server
pnpm start

The installation process automatically:

1. Gets the latest version of Payload CMS
2. Generates MCP tools from Payload types
3. Builds the server ready for use

Using with Cursor

To use the MCP server with Cursor or other MCP-compatible clients:

1. Run the server in stdio-only mode (default):

   payload-cms-mcp

2. In Cursor, add the MCP server:

   • Click on the MCP Servers button in the sidebar
   • Click "Add new MCP server"
   • Enter a name (e.g., "payload-cms-mcp")
   • Select "sse" as the type
   • Enter the path to your server executable (e.g., /usr/local/bin/payload-cms-mcp)
   • Click "Save"

3. The MCP server should now be available in Cursor. You can use the tools to generate Payload CMS code.

Available Tools

The following tools are auto-generated from Payload CMS 3.0 type definitions:

• createCollection: Creates a collection configuration
• createGlobal: Creates a global configuration
• createTextField: Creates a text field configuration
• createEmailField: Creates an email field configuration
• createNumberField: Creates a number field configuration
• createDateField: Creates a date field configuration
• createRelationshipField: Creates a relationship field
• createArrayField: Creates an array field configuration
• createBlocksField: Creates a blocks field configuration
• And many more field types...

Each tool accepts parameters based on the Payload CMS type definitions and returns properly formatted code.

Development

Regenerating Tools

If you update Payload CMS or want to regenerate the tools:

# Update Payload
pnpm add payload@latest

# Regenerate tools
pnpm generate-tools

Logging

The server uses console-based logging with various severity levels. Logs are printed to the console (stdout/stderr).

The server uses npm-style logging levels:

Level	Description
error	Error conditions
warn	Warning conditions
info	Informational messages
http	HTTP transaction messages
verbose	Detailed information
debug	Debug information for troubleshooting
silly	Extra verbose debugging information

By default, the log level is set to info, which means only logs with level info, warn, and error will be recorded. To see more detailed logs:

• Set to verbose to see tool registration details
• Set to debug for more detailed debugging information

You can change the log level by setting the LOG_LEVEL environment variable:

# Run with verbose logging
LOG_LEVEL=verbose payload-cms-mcp

# Or set in .env file
# LOG_LEVEL=verbose

License

MIT

Author

Govcraft