# Royal MCP’s ACF Tools — Reference

> Four free Royal MCP tools let Claude, ChatGPT and Perplexity read and write Advanced Custom Fields data, with type-aware writes and hydrated return values.

- Canonical: <https://royalplugins.com/support/royal-mcp/acf-tools/>
- Last updated: 2026-09-22
- HTML version: <https://royalplugins.com/support/royal-mcp/acf-tools/>

---

Four free tools that let Claude, ChatGPT, or Perplexity read and write Advanced Custom Fields data through Royal MCP. Type-aware writes for text, numbers, repeaters, flexible content, relationships, and images; hydrated reads that flatten WP\_Post, WP\_User, and WP\_Term objects to compact JSON.

## How ACF + Royal MCP works

When [Advanced Custom Fields](https://wordpress.org/plugins/advanced-custom-fields/) (free or Pro) is active, Royal MCP registers **4 additional tools** for reading and writing ACF fields. Added in v1.4.24.

You might wonder why a dedicated integration exists when `wp_get_post_meta` already returns custom-field data. The answer is Return Format. WordPress’s meta API returns raw stored values: serialized arrays for repeaters, raw IDs for relationships, raw attachment IDs for image fields. ACF’s `get_field()` and `update_field()` respect each field’s Return Format and hydrate values per field type, matching the view a human editor sees in the ACF UI. An AI agent interacting with ACF wants that formatted view, not the raw serialized one.

## The four free ACF tools

acf\_get\_field

Read one ACF field by name or key, formatted per its Return Format setting. Returns hydrated post objects, parsed repeater rows, and image arrays.

acf\_get\_fields

Read every ACF field defined on a post in one call, with name, label, type, and value bundled per field. The most efficient way to discover what fields exist and read them all.

acf\_update\_field

Write a field value with type-aware handling: scalar for text and numbers, array for repeaters and flexible content, post ID for relationships, attachment ID for images.

acf\_get\_field\_groups

Enumerate ACF field groups on the site, optionally filtered by post type. Use this for AI-driven discovery of what custom fields are available before reading or writing.

## Return-Format hydration

For relationship, post\_object, user, and taxonomy fields configured with Return Format “Object”, Royal MCP flattens WordPress objects to small JSON-friendly arrays so an AI client gets useful structure instead of raw `WP_Post`, `WP_User`, or `WP_Term` objects in the response.

Hydration shapes

Post: `id, title, post_type, status, permalink`. User: `id, display_name, user_email`. Term: `id, name, slug, taxonomy`. Repeaters and flexible content pass through as arrays with each row hydrated the same way.

## Example queries

Ask Claude, ChatGPT, or Perplexity questions like these once ACF + Royal MCP are connected:

- “List the ACF field groups on this site and the fields in each one.”
- “Read all ACF fields for post ID 142 and show me their values.”
- “Get the `subtitle` field value for the post titled ‘Launch Announcement’.”
- “Update the `featured_quote` field on post 142 to a new value.”
- “Which ACF field groups apply to the Product post type?”
- “Read the `related_posts` field on post 88 and give me the titles and permalinks.”

## Pro ACF toolkit — programmatic field-group authoring

The free four tools cover reading and writing existing fields. Authoring new field groups programmatically (the ACF “setup” side, rather than the runtime read/write side) lives in **Royal MCP Pro**. Use it to define custom fields for a new post type in a single MCP call, migrate field-group configs between environments, or let Claude scaffold a bespoke field set from a brief.

[Pro Reference

ACF Setup Suite

Programmatic field-group authoring: create field groups, define fields of any ACF type, configure location rules and conditional logic, and export or import group configs for portability.](https://royalplugins.com/support/royal-mcp-pro/acf-setup-suite/)

## Permissions & safety

ACF read operations require `read_post` on the target, and write operations require `edit_post`. Royal MCP enforces WordPress’s standard capability checks on every ACF tool call, so an AI client can only read or write the fields the connecting user has permission to touch.

Field keys vs. field names

ACF supports both stable field keys (like `field_5f8a2b`) and human-readable names (like `featured_quote`). Prefer keys in scripted workflows because they survive field renames, but names are fine for one-off reads and writes an AI agent constructs on the fly.

Repeater and flexible-content writes

When writing a repeater or flexible-content field, pass the full array of rows, not a partial update. ACF replaces the entire field value on write. To edit one row, read the current value, modify the row in memory, and write the whole array back.

[Back to Royal MCP Support](https://royalplugins.com/support/royal-mcp/)
[WooCommerce Tools Reference](https://royalplugins.com/support/royal-mcp/woocommerce-tools/)