ACF MCP Server

Production-ready Model Context Protocol server for safely reading and changing WordPress + ACF Pro structure through ACF Local JSON and explicit WP-CLI synchronization.

The server is built for AI agents that need to inspect or propose changes to ACF field groups, custom post types, taxonomies, and options pages without direct database access.

Features

• TypeScript, Node.js, Zod, Vitest, and @modelcontextprotocol/sdk.
• JSON-first ACF Local JSON repository.
• No direct SQL, no arbitrary PHP, no shell interpolation.
• Automatic backups before mutations.
• dryRun support for write workflows.
• Explicit WP-CLI sync/import/export tools.
• stdio transport by default, optional Streamable HTTP for development.
• DDEV WordPress fixture configuration.

Install

npm install
npm run build

For local development:

export ACF_MCP_ACF_JSON_DIR="/absolute/path/to/wp-content/themes/my-theme/acf-json"
export ACF_MCP_WP_ROOT="/absolute/path/to/wordpress"
npm run dev

MCP Client Configuration

Example stdio configuration:

{
  "mcpServers": {
    "acf": {
      "command": "node",
      "args": ["/absolute/path/to/acf_mcp/dist/server/stdio.js"],
      "env": {
        "ACF_MCP_ACF_JSON_DIR": "/absolute/path/to/wp-content/themes/my-theme/acf-json",
        "ACF_MCP_WP_ROOT": "/absolute/path/to/wordpress"
      }
    }
  }
}

During development, use tsx:

{
  "command": "npx",
  "args": ["tsx", "/absolute/path/to/acf_mcp/src/server/stdio.ts"]
}

Safety Model

Local JSON is the primary source of truth. Tools that create, update, delete, or apply content models write JSON files only. They do not sync the WordPress database automatically.

Recommended workflow:

1. Call a write tool with dryRun: true.
2. Review the planned changes.
3. Call the same tool with dryRun: false.
4. Review git diff for acf-json.
5. Call acf_sync_json with dryRun: true.
6. Call acf_sync_json with dryRun: false only when ready.

Tools

• acf_ping
• acf_list_field_groups
• acf_get_field_group
• acf_create_field_group
• acf_update_field_group
• acf_delete_field_group
• acf_validate_field_group
• acf_export_json
• acf_import_json
• acf_sync_json
• acf_list_post_types
• acf_create_post_type
• acf_list_taxonomies
• acf_create_taxonomy
• acf_list_options_pages
• acf_create_options_page
• acf_apply_content_model

See docs/tools.md for schemas and examples.

Example: Apply a Content Model

{
  "dryRun": true,
  "backup": true,
  "model": {
    "postTypes": [
      {
        "key": "post_type_product",
        "post_type": "product",
        "labels": { "name": "Products", "singular_name": "Product" },
        "public": true,
        "show_in_rest": true
      }
    ],
    "taxonomies": [
      {
        "key": "taxonomy_brand",
        "taxonomy": "brand",
        "object_type": ["product"],
        "labels": { "name": "Brands", "singular_name": "Brand" }
      }
    ],
    "optionsPages": [
      {
        "key": "ui_options_page_theme_settings",
        "menu_slug": "theme-settings",
        "page_title": "Theme Settings"
      }
    ],
    "fieldGroups": [
      {
        "key": "group_product_details",
        "title": "Product Details",
        "fields": [
          {
            "key": "field_product_subtitle",
            "label": "Subtitle",
            "name": "subtitle",
            "type": "text"
          }
        ],
        "location": [
          [{ "param": "post_type", "operator": "==", "value": "product" }]
        ]
      }
    ]
  }
}

DDEV

This repository includes .ddev/config.yaml for a WordPress fixture in wp/.

ACF Pro is not bundled or redistributed. Install your licensed ACF Pro copy in the fixture when running WordPress integration checks.

See docs/ddev.md.

Development

npm run typecheck
npm run lint
npm test
npm run build

Optional integration tests can be added under tests/integration and gated with:

RUN_DDEV_INTEGRATION=1 npm run test:integration

Project Structure

src/
  adapters/
  config/
  errors/
  prompts/
  repositories/
  resources/
  schemas/
  server/
  services/
  tools/
  types/
  utils/

Contributing

Keep changes small, tested, and backward-compatible. New tools must include:

• Zod input schema.
• Typed structured result.
• Error handling through the shared tool wrapper.
• Tests for success, validation failure, and dry-run behavior when mutating.

License

MIT