Payload

You can connect your AI assistants and tools directly to your Payload CMS instance with a dedicated MCP server. It handles authentication, token management, and provides a secure set of operations to create, search, and update objects, as well as read and modify global documents across your Payload collections.

How to use

You use an MCP client to communicate with the Payload MCP server. Start the server locally or in your development environment, then connect your client using the provided command configuration. Once connected, you can perform common operations such as creating new objects, searching for items with filters and pagination, updating existing documents by ID, and managing global configurations with localization support. If authentication is required, your client will prompt you to log in or refresh tokens automatically.

How to install

Prerequisites: You need Python 3.8 or newer. You should have a Payload CMS instance running and accessible at a base API URL, typically http://localhost:3000/api.

Step 1: Clone the MCP server repository and install dependencies.

git clone https://github.com/ohnicholas93/payload-mcp-server.git
cd payload-mcp-server
pip install -r requirements.txt

Step 2: Optionally install the package globally for convenient access.

pip install .

Step 3: Create and configure the environment file to point to your Payload instance and set runtime behavior.

cp .env.example .env

Edit .env to specify at minimum the base Payload URL and any authentication or SSL preferences, for example:

PAYLOAD_MCP_PAYLOAD__BASE_URL=http://localhost:3000/api
PAYLOAD_MCP_PAYLOAD__AUTH_TOKEN=YOUR_JWT_TOKEN
PAYLOAD_MCP_PAYLOAD__TIMEOUT=30
PAYLOAD_MCP_PAYLOAD__VERIFY_SSL=false
PAYLOAD_MCP_PAYLOAD__BYPASS_PROXY=true
PAYLOAD_MCP_LOG_LEVEL=INFO

Configuration and running

Run the server and verify it starts successfully. The server will listen for MCP protocol communication on standard input/output.

Start the server using one of the documented commands.

payload-mcp-server

Or run it directly from Python:

python -m payload_mcp.server

## Integrating with an MCP client

Configure your MCP client (for example in VS Code) to load the Payload MCP server so you can access the tools directly from prompts. Create or edit your MCP configuration to include a server that runs the MCP entry point and points to your project root.

Example client configuration (adjust the root path to your environment):

{ "mcpServers": { "payload": { "command": "python", "args": ["-m", "payload_mcp.server"], "cwd": "<path-to-root>" } } }

## Usage examples

Create an object: you can add a new document to a collection by calling the create\_object tool with the collection name and the data for the new entry.

Search objects: perform a query on a collection with filters, then limit and sort the results as needed.

Update an object: modify a document by its ID with the new data you provide.

## Security and authentication

The server handles authentication, including JWT token management and optional browser-based login if needed. Ensure your Payload user has the necessary permissions to perform the requested actions.

## Troubleshooting

Connection issues usually mean Payload is not reachable at the configured URL. Check that the Payload instance is running and accessible, and verify the base URL in your environment configuration.

Authentication issues may require re-authentication or refreshing tokens. If you see token-related errors, verify the token or allow the browser login flow if prompted.

## Available tools

### create\_object

Create one or multiple new objects in a specified collection, supporting single objects or arrays for batch creation.

### search\_objects

Search a collection with filters, pagination, sorting, localization, and population support.

### update\_object

Update an object by its ID with updated data, supporting partial updates.

### get\_global

Read a global document by its slug with localization and population options.

### update\_global

Update a global document by its slug with localization and population options.