Content
# 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
```bash
npm install
npm run build
```
For local development:
```bash
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:
```json
{
"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`:
```json
{
"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](docs/tools.md) for schemas and examples.
## Example: Apply a Content Model
```json
{
"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](docs/ddev.md).
## Development
```bash
npm run typecheck
npm run lint
npm test
npm run build
```
Optional integration tests can be added under `tests/integration` and gated with:
```bash
RUN_DDEV_INTEGRATION=1 npm run test:integration
```
## Project Structure
```text
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
