npm package: @govcraft/payload-cms-mcp
Description: Payload MCP Server - A Model Context Protocol server for Payload CMS 3.0
Author: roland@govcraft.ai
Latest version: 1.0.10

# 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)

```bash
# 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:

```bash
# 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

```bash
# 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):
   ```bash
   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:

```bash
# 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:

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

# Or set in .env file
# LOG_LEVEL=verbose
```

## License

MIT

## Author

[Govcraft](https://github.com/Govcraft)