Acf 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.

ACF 6.8 also exposes ACF schema and content through the WordPress Abilities API when paired with the MCP Adapter plugin or another MCP server implementation. This project complements that runtime path with a repo-first workflow: Local JSON remains the source of truth, changes are reviewable in git, and WordPress synchronization is explicit.

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.
• ACF 6.8 runtime-readiness audits for AI access, REST visibility, and location references.
• Simplified creation tools using ACF Abilities-style inputs.
• Read-only Schema.org mapping audits for ACF field metadata.
• 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_create_field_group_simple
• acf_update_field_group
• acf_delete_field_group
• acf_validate_field_group
• acf_audit_ai_access
• acf_validate_runtime_compatibility
• acf_audit_schema_mappings
• acf_runtime_status
• acf_export_json
• acf_import_json
• acf_sync_json
• acf_list_post_types
• acf_create_post_type
• acf_create_post_type_simple
• acf_list_taxonomies
• acf_create_taxonomy
• acf_create_taxonomy_simple
• acf_list_options_pages
• acf_create_options_page
• acf_apply_content_model

See docs/tools.md for schemas and examples. See docs/runtime-compatibility.md for ACF 6.8 Abilities API, MCP Adapter, and Schema.org guidance.

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/

Explore ACF Pro skill for AI agents

https://github.com/symonbaikov/acf-pro-skill

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