Payload CMS MCP Server

Overview

This is a Model Context Protocol (MCP) server that enables AI assistants and tools to interact directly with your Payload CMS instance. It provides a set of secure, authenticated tools for common operations like creating, searching, and updating objects in your Payload collections via the REST API.

The server handles authentication automatically, including JWT token management and browser-based login flows if needed. It's designed to be lightweight, configurable, and easy to integrate into development workflows (e.g., with VS Code and Kilocode), with support for both Linux and Windows environments.

Features

• Create Objects: Add new documents to any collection, supporting single objects or batches.

• Search Objects: Query collections with filters (MongoDB-like where clauses), pagination, sorting, localization, and population of related fields.

• Update Objects: Modify existing documents by ID, with support for partial updates.

• Globals Support: Read and update Global documents by their slug, with full localization and population support.

• MCP Resources Support: Exposes concrete payload://server/* resources plus templates for collections, documents, and globals through resources/list, resources/read, and resources/templates/list.

• Authentication Handling: Automatic JWT token refresh, stored credentials, and interactive browser login for seamless auth.

• Localization Support: Works with Payload's i18n features; specify locales in tool calls.

• Error Handling: Comprehensive exceptions for validation, auth, API, and connection issues.

• Configurable: Override Payload host, timeouts, SSL, and logging via environment variables.

MCP Resources

This server now exposes MCP resources in addition to tools.

Concrete Resources

• payload://server/info: Server and Payload connection metadata.

• payload://server/auth: Authentication state summary.

• payload://server/resources: Usage guide for the resource URI formats.

Resource Templates

• payload://collections/{collection}: Read a collection listing. Supports query params such as limit, page, sort, depth, locale, fallback-locale, trash, where, select, populate, and joins.

• payload://collections/{collection}/{id}: Read a single collection document by ID. Supports depth, locale, fallback-locale, draft, select, populate, and joins.

• payload://globals/{slug}: Read a global document by slug. Supports depth, locale, fallback-locale, select, and populate.

For where, select, populate, and joins, pass a JSON object as the value and URL-encode that JSON in the query string.

Example URIs:

payload://collections/posts?limit=5&sort=-updatedAt
payload://collections/posts?where=%7B%22status%22%3A%7B%22equals%22%3A%22published%22%7D%7D
payload://collections/posts/123?depth=1
payload://globals/header?depth=1

Tool Schemas

The available tools and their input schemas (JSON Schema format) are listed below. These define the parameters for each tool call.

create_object

Description: Create one or multiple new object(s) in a specified collection.

{
  "type": "object",
  "properties": {
    "collection_name": {
      "type": "string",
      "description": "Name of the collection to create object in"
    },
    "data": {
      "oneOf": [
        {
          "type": "object",
          "description": "Object data to create"
        },
        {
          "type": "array",
          "items": {
            "type": "object"
          },
          "description": "Array of objects to create"
        },
        {
          "type": "string",
          "description": "JSON-encoded object or array of objects to create"
        }
      ],
      "description": "Object data, array of objects, or a JSON-encoded object/array to create"
    },
    "locale": {
      "type": "string",
      "description": "Locale code for the operation (e.g., 'en', 'es'). If not provided and localization is enabled, only the ONE default locale will be used"
    }
  },
  "required": ["collection_name", "data"]
}

search_objects

Description: Search objects in a collection.

{
  "type": "object",
  "properties": {
    "collection_name": {
      "type": "string",
      "description": "Name of the collection to search in"
    },
    "query": {
      "type": "object",
      "description": "Search query parameters (MongoDB-like where clause)"
    },
    "limit": {
      "type": "integer",
      "description": "Maximum number of results to return"
    },
    "page": {
      "type": "integer",
      "description": "Page number for pagination"
    },
    "sort": {
      "type": "string",
      "description": "Sort field and direction"
    },
    "locale": {
      "type": "string",
      "description": "Locale code for the operation (e.g., 'en', 'es'). If not provided and localization is enabled, only the ONE default locale will be used"
    }
  },
  "required": ["collection_name"]
}

update_object

Description: Update an object by ID.

{
  "type": "object",
  "properties": {
    "collection_name": {
      "type": "string",
      "description": "Name of the collection containing the object"
    },
    "object_id": {
      "type": "string",
      "description": "ID of the object to update"
    },
    "data": {
      "type": "object",
      "description": "Updated object data"
    },
    "locale": {
      "type": "string",
      "description": "Locale code for the operation (e.g., 'en', 'es'). If not provided and localization is enabled, only the ONE default locale will be used"
    }
  },
  "required": ["collection_name", "object_id", "data"]
}

get_global

Description: Get a global document by its slug.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "The slug of the global to retrieve"
    },
    "locale": {
      "type": "string",
      "description": "Locale code for the operation (e.g., 'en', 'es'). If not provided and localization is enabled, only the ONE default locale will be used"
    },
    "depth": {
      "type": "integer",
      "description": "Controls the depth of population for relationships"
    },
    "fallback_locale": {
      "type": "string",
      "description": "Specifies a fallback locale if the requested locale is not available"
    },
    "select": {
      "type": "object",
      "description": "Fields to include in the result"
    },
    "populate": {
      "type": "object",
      "description": "Fields to populate from related documents"
    }
  },
  "required": ["slug"]
}

update_global

Description: Update a global document by its slug.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "The slug of the global to update"
    },
    "data": {
      "type": "object",
      "description": "Updated global data"
    },
    "locale": {
      "type": "string",
      "description": "Locale code for the operation (e.g., 'en', 'es'). If not provided and localization is enabled, only the ONE default locale will be used"
    },
    "depth": {
      "type": "integer",
      "description": "Controls the depth of population for relationships in response"
    },
    "fallback_locale": {
      "type": "string",
      "description": "Specifies a fallback locale if the requested locale is not available"
    }
  },
  "required": ["slug", "data"]
}

Prerequisites

Before setting up and using this MCP server, ensure the following:

1. Python 3.8+: The server is built with Python and requires version 3.8 or higher.

2. Running Payload CMS Instance:

   • Your Payload CMS must be up and running.

   • Default assumption: Accessible at http://localhost:3000/api.

   • By the time the first tool call is made (e.g., from your MCP client), the Payload instance must already be accessible.

   • If your Payload is hosted elsewhere (e.g., remote server), configure the base URL via environment variables (see Configuration section).

3. MCP-Compatible Client:

   • An MCP client like Kilocode in VS Code, Cursor, or similar AI development tools that support MCP servers.

   • Ensure your client can execute external commands (e.g., run the server binary).

Note: No additional database setup or Payload configuration is needed beyond having a working instance. The server does not start or manage Payload for you—handle that separately.

Installation

1. Clone the Repository:

   git clone https://github.com/your-org/payload-mcp.git
   cd payload-mcp

2. Install Dependencies: Install the required Python packages. This includes MCP protocol support, HTTP client, and configuration libraries.

   pip install -r requirements.txt

   Alternatively, install the full package (recommended for global use):

   pip install .

   This makes the payload-mcp-server command available in your PATH. The server and browser-auth launch flow are intended to work on both Linux and Windows.

3. Set Up Environment: Copy the example environment file and customize it:

   cp .env.example .env

   Edit .env as needed (see Configuration below). Add .env to your .gitignore if not already (it is by default).

Configuration

The server uses Pydantic for type-safe configuration loaded from environment variables. Most users can rely on defaults, but customize via .env for non-local setups.

Key Environment Variables

From .env.example:

• Payload CMS Connection:

  • PAYLOAD_MCP_PAYLOAD__BASE_URL: Base API URL (default: http://localhost:3000/api). Override for remote hosts, e.g., https://your-site.com/api.

  • PAYLOAD_MCP_PAYLOAD__AUTH_TOKEN: Optional JWT token for pre-authenticated access. If omitted, browser login will be used on first need.

  • PAYLOAD_MCP_PAYLOAD__TIMEOUT: Request timeout in seconds (default: 30).

  • PAYLOAD_MCP_PAYLOAD__VERIFY_SSL: Enable SSL verification (default: false for local dev; set to true for HTTPS production).

  • PAYLOAD_MCP_PAYLOAD__BYPASS_PROXY: Bypass proxies for localhost (default: true).

• Server Settings:

  • PAYLOAD_MCP_LOG_LEVEL: Logging verbosity (default: INFO; options: DEBUG, INFO, WARNING, ERROR, CRITICAL).

Example .env for Remote Payload:

PAYLOAD_MCP_PAYLOAD__BASE_URL=https://myapp.com/api
PAYLOAD_MCP_PAYLOAD__AUTH_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
PAYLOAD_MCP_PAYLOAD__VERIFY_SSL=true
PAYLOAD_MCP_LOG_LEVEL=DEBUG

Testing

This project can be tested with Python's built-in unittest runner.

./.venv/bin/python -m unittest discover -s tests -v

Reload the server after config changes.

Running the Server

1. Start the MCP Server: After installation, run:

   payload-mcp-server

   Or directly from source:

   python -m payload_mcp.server

   • The server initializes, loads config, and tests basic connectivity (logs any issues but continues).

   • It listens on stdio for MCP protocol communication.

   • Logs will show connection status and any auth prompts.

2. Background/Production:

   • For persistent runs, use tools like nohup, screen, or systemd.

   • Example: nohup payload-mcp-server > server.log 2>&1 &

The server does not require Payload to be running during startup—only when tools are called. However, ensure Payload is accessible before tool use.

Integrating with MCP Client

1. Add to Client (e.g., VS Code with Kilocode):

   • Open your MCP client settings (e.g., in VS Code: Ctrl+Shift+P > "Kilocode: Edit MCP Config").

   • Add a new server configuration to your MCP settings file (usually mcp.json or similar).

   • Use the following example configuration, replacing <swap to root directory of the mcp server> with the actual path to this project's root directory:

   {
     "mcpServers": {
       "payload-mcp": {
         "command": "python",
         "args": ["-m", "payload_mcp.server"],
         "cwd": "<swap to root directory of the mcp server>"
       }
     }
   }

   • Save the settings and restart/reload your MCP client.

   • The client will automatically start the server when needed and list the available tools (e.g., create_object, search_objects, update_object, get_global, update_global).

2. Verify Integration:

   • In your MCP client, query for available tools. You should see the Payload CMS tools listed.

   • Test a simple tool call, like searching a collection, to ensure authentication and connectivity work.

   • If browser auth is triggered, follow the prompts to log in to your Payload instance.

Usage Examples

Once integrated, you can use the tools in your AI assistant prompts. Examples:

• Create an Object:

  Use the create_object tool to add a new user to the 'users' collection with name: "John Doe" and email: "john@example.com".

• Search Objects:

  Search the 'posts' collection for items where title contains "Payload" and limit to 5 results.

• Update an Object:

  Update the user with ID "123" in the 'users' collection to set email to "john@newemail.com".

The tools support advanced parameters like locales, population, and complex queries—refer to the tool schemas above for full details.

Troubleshooting

• Connection Errors: Ensure Payload is running and accessible at the configured URL. Check logs for details.

• Authentication Issues: Provide a valid JWT token in .env or allow browser login. Verify your Payload user has necessary permissions.

• Tool Not Found: Restart the MCP client after adding the server config.

• Logs: Set PAYLOAD_MCP_LOG_LEVEL=DEBUG for verbose output.

• Windows/PowerShell: Commands use standard syntax; use python.exe if python is ambiguous.

Contributing

• Fork the repo and create a pull request.

• Install dev dependencies if adding features.

• Follow PEP 8 style and add tests where applicable.

License

MIT License. See LICENSE for details (add if needed).

For support, check the Payload CMS docs or open an issue.