wagtail-mcp

Wagtail MCP Server

This project implements a Model Context Protocol (MCP) server that provides read-only access to a Wagtail CMS instance using its V2 API. It is built on FastMCP.

Configuration

Add the following JSON to the MCP configuration file for your environment (e.g. claude_desktop_config.json for Claude Desktop):

{
  "mcpServers": {
    "wagtail-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "wagtail-mcp"
      ],
      "env": {
        "WAGTAIL_BASE_URL": "https://api.example.com"
      }
    }
  }
}

Make sure to set WAGTAIL_BASE_URL to the base URL of your Wagtail API instance.

Implemented Tools

• search_pages: Searches pages from the Wagtail CMS API.

  • Parameters:
    • query (string): The term to search for in page content.
    • type (string, optional): Filters results to a specific page type (e.g., blog.BlogPage, myapp.StandardPage).
    • locale (string, optional, default: en): Filters pages by a specific locale code (e.g., en for English, es for Spanish).
    • search_operator (string, optional, values: and, or): Determines how multiple terms in the query are combined. Defaults based on the Wagtail search backend configuration.
    • limit (integer, optional, default: 50): The maximum number of page results to return.
    • offset (integer, optional): The starting point for paginated results (e.g., an offset of 10 skips the first 10 results).
    • fields (string, optional): A comma-separated list to control which fields are returned in the response for each page. Examples: title,body (returns only title and body), *,-summary (returns all fields except summary), _,custom_field_name (returns default fields plus a specific custom field). Refer to Wagtail API documentation for more on field selection syntax.
  • Usage: Useful for finding pages matching certain keywords, potentially filtered by their type or language. For example, searching for all "news" articles in Spanish. Returns a list of pages with their details.

• get_page_details: Retrieves the full details of a specific Wagtail page.

  • Parameters (at least one of id, slug, or url is required; priority is id > slug > url):
    • id (integer, optional): The unique numeric ID of the page.
    • slug (string, optional): The slug (URL path component) of the page (e.g., about-us/team).
    • url (string, optional): The full public URL of the page.
    • fields (string, optional): A comma-separated list to control which fields are returned in the response. This allows for fetching specific data points or excluding others.
      • Examples:
        • body,feed_image: Returns only the body and feed_image fields.
        • *,-title: Returns all fields except title.
        • _,my_custom_field: Returns default fields plus my_custom_field. (Refer to Wagtail API documentation for more on field selection syntax).
  • Usage: Use this to fetch comprehensive data for a known page, such as its content, metadata, or custom fields, after identifying it via search_pages or other means. Returns the full page object.

• search_documents: Searches for Wagtail documents (e.g., PDFs, images uploaded to the media library).

  • Parameters:
    • query (string, required): The search term to use for finding documents by their title or other indexed metadata.
    • search_operator (string, optional, values: and, or, default: and): Specifies how multiple terms in the query are combined (and requires all terms to match, or requires at least one).
  • Usage: Helps locate documents within the Wagtail CMS based on keywords. For instance, finding all PDF documents containing "annual report". Returns a list of matching documents including their ID, title, and download URL.

• get_document_details: Retrieves detailed information for a specific Wagtail document.

  • Parameters:
    • id (integer, required): The unique numeric ID of the document.
  • Usage: After finding a document's ID (e.g., via search_documents), use this to get its specific details, primarily its ID, title and download URL.

Configuration Details

Environment variables can be passed in via the MCP configuration file for your environment (e.g. claude_desktop_config.json):

• Wagtail API Configuration:
  • WAGTAIL_BASE_URL: Required. The base URL of your Wagtail API instance (e.g., https://api.example.com).
  • WAGTAIL_API_PATH: (Optional) Path to the API endpoint. Defaults to /api/v2.
  • WAGTAIL_API_KEY: (Optional) An API key if your Wagtail API requires bearer token authentication.