payload

Payload MCP Server provides a secure, authenticated bridge to your Payload CMS instance. It exposes tools to create, search, and update documents in any Payload collection, as well as read and modify Global documents with full localization and population support. The server handles authentication automatically, including JWT token refresh and optional interactive login flows. Clients (like Kilocode, VS Code MCP integrations, or your own tooling) can call the defined tools by specifying the appropriate input schemas (e.g., create_object, search_objects, update_object, get_global, update_global). Use these tools to perform common CMS operations from your AI-assisted workflows without direct manual API calls. The server is designed to be lightweight and configurable, with environment variables controlling the base URL, authentication, and logging, making it simple to integrate into development pipelines and local setups.

Prerequisites

• Python 3.8+
• A running Payload CMS instance (default base API URL: http://localhost:3000/api)
• A working MCP client (e.g., Kilocode in VS Code) capable of calling external commands

Installation steps

1. Clone the repository and install the package (assuming you’re using the published package name after cloning):

git clone https://github.com/ohnicholas93/payload-mcp-server.git
cd payload-mcp-server

2. Install Python dependencies (recommended for local development):

pip install -r requirements.txt

3. Optional: install the package globally for easier access from any shell:

pip install .

This should expose the payload-mcp-server command in your PATH.

4. Prepare configuration

cp .env.example .env

Edit .env as needed (e.g., set PAYLOAD_MCP_PAYLOAD__BASE_URL to your Payload API URL).

5. Run the server

payload-mcp-server

Or run via Python module directly (useful in virtual environments):

p python -m payload_mcp_server

6. Verify accessibility If the server starts successfully, you should see log lines indicating the MCP server is listening for tool calls at the configured base URL.

Tips and common considerations:

• Ensure your Payload CMS is reachable from the machine running the MCP server. If you’re using a remote Payload instance, set PAYLOAD_MCP_PAYLOAD__BASE_URL accordingly.
• The MCP tools support localization flags (locale) and population (populate) when needed. Use the provided JSON Schemas in the README to structure your tool calls.
• If you encounter authentication issues, verify that environment variables for tokens or credentials are correctly set and that any interactive login flows are accessible in your environment.
• For development, enable DEBUG logs by setting PAYLOAD_MCP_LOG_LEVEL=DEBUG to get more granular information about requests and errors.
• Keep your Payload CMS CORS and authentication requirements in mind; the MCP server handles token refresh, but the initial login flow may require browser-based authentication depending on your setup.
• When deploying, consider securing environment variables via your platform’s secret management and restricting network access to trusted clients.