AEM Content Manager (ACM)

ACM MCP Server

A Model Context Protocol server that connects AI agents (Claude Code, Claude Desktop, VS Code, Cursor and other MCP clients) to AEM Content Manager (ACM) running on Adobe Experience Manager, including AEM as a Cloud Service.

An agent can validate and run Groovy scripts on AEM through ACM, follow long-running executions, read execution history and console output, and browse the scripts stored on the instance — on any of the configured instances, so it can also compare author against publish or against another environment. Every call runs as the user whose credentials you configure.

graph LR

client["MCP client (Claude, ...)"] <-- "stdio (MCP)" --> server["acm-mcp-server (your machine)"] server <-- "HTTPS" --> aem["AEM instances + ACM /apps/acm/api/*.json"]

[!WARNING]

This server lets an AI agent run arbitrary Groovy code on AEM with your permissions. Read Security before pointing it at a shared or production instance.

[!TIP]

Using VS Code? The ACM extension bundles this server and registers it for all enabled instances, with credentials from VS Code's secret storage. No setup below is needed — and ACM: Export MCP Config writes a ready config file for other agents.

Requirements

• Node.js 22 or later.
• ACM installed on each AEM instance. Running code without history (history: false) needs ACM 0.9.74 or later.
• A user with access to the ACM API on each instance (see Permissions).

Setup

The server is configured by a JSON document using the same keys as the VS Code extension settings, including the acm. prefix — a block copied from settings.json is a valid config:

{

"acm.instances": [ { "name": "local-author", "url": "http://localhost:4502", "authMode": "basic", "user": "admin" }, { "name": "local-publish", "url": "http://localhost:4503", "authMode": "basic", "user": "admin" }, { "name": "dev", "url": "https://author-pXXXX-eYYYY.adobeaemcloud.com", "authMode": "bearer", "secret": { "env": "ACM_DEV_TOKEN" }, "readonly": true }, { "name": "prod", "url": "https://author.example.com", "authMode": "cookie", "secret": { "file": "~/.config/acm/prod.cookie" }, "enabled": false } ], "acm.activeInstance": "local-author", "acm.http.timeout": 30000, "acm.run.timeout": 120000, "acm.run.pollInterval": 1000 }

The timeout keys are optional; their defaults are shown. Unknown keys are ignored, so a whole settings block can be pasted.

1. Create the config file

Instance fields:

Choosing credentials:

The login-token cookie expires after about 12 hours; use secret: { "file": "path" } to refresh it without restarting the server.

Secrets

secret is the bearer token, the login-token cookie (value or name=value) or the basic-auth password, given as:

• a literal — convenient for development. Keep the config file readable only by you (chmod 600); the server warns when it is not.
• { "env": "NAME" } — read from an environment variable of the server process. Nothing is written to the config file.
• { "file": "path" } — ~ is expanded and a relative path resolves against the config file. Re-read on every request, so refreshing a token on disk needs no restart. A missing or empty file fails only that instance.

Basic auth with user admin on a local URL defaults to password admin, so the local SDK needs no secret at all.

2. Register the server with your agent

Every MCP client needs the same things. Where they go and in which format depends on the client, so this guide does not list client-specific files:

Instead of ACM_CONFIG_FILE you can pass the document inline as ACM_CONFIG; it takes precedence over the file.

The easiest way is to ask your agent, which knows its own configuration:

Add the ACM MCP server to this tool's MCP configuration: transport stdio, command npx, arguments -y @wppes/acm-mcp-server, environment ACM_CONFIG_FILE pointing at a JSON file with the ACM instances I list below. Keep secrets out of that file — reference environment variables or files instead — and never write them into a file that may be committed; tell me where to put the values. Find in this tool's documentation where MCP servers are configured and in which format. Then call acm_list_instances and acm_health to verify.

3. Check the connection

Ask the agent to call acm_list_instances, then acm_health. The first shows every enabled instance with its auth mode and whether credentials are configured; the second reports the state ACM reports for each of them.

Instances

Tools act on exactly one instance, chosen like this:

1. the optional instance argument, when given — it must name an enabled instance;
2. otherwise acm.activeInstance, when it names an enabled instance;
3. otherwise the only enabled instance, when just one is configured;
4. otherwise the call fails with the list of enabled names, so nothing runs on the wrong instance by accident.

If acm.activeInstance names an unknown or disabled instance (a typo, say), the server warns on stderr at startup and acm_list_instances repeats the warning, so the agent can tell you; the rules above then apply as if it were unset.

acm_list_instances shows which instance is active and which have credentials. Write tools (acm_run_code, acm_abort_execution, acm_describe_inputs) always act on exactly one instance — there is deliberately no run-everywhere call. To compare instances (e.g. author vs publish drift), run the same read-only code on each and diff the results; the bundled scripting guide covers the pattern. This needs ACM reachable on both sides, which works on local, on-premise and AMS (direct publish URL) — an AEMaaCS publish is not reachable.

Tools

Every tool takes an optional instance argument; see Instances for the default.

Bare Groovy snippets are wrapped in the canRun()/doRun() structure automatically, so println "hello" is valid input for acm_validate_code and acm_run_code.

Runs without history

Every queued run is stored in ACM execution history, so iterating on a script quickly fills it up. With history: false, acm_run_code calls /apps/acm/api/execute-code.json directly and the run is not recorded. Such a run:

• has no execution ID to poll or abort, and keeps no output files;
• is cut off on the client side after waitMs, while the script may keep running on AEM.

Use it for short read-only runs or dry runs while you develop a script. Run the final version, and anything that changes content, with the default history: true so the change stays auditable.

Running without history needs the console/execute/nohistory ACM feature (administrators only by default); without it the call fails with 403. Such runs still appear in ACM's audit log.

Scripting guide

The server ships the ACM Groovy scripting skill, so agents write valid, safe scripts without extra setup:

• Instructions. The skill's essentials (never invent API, dry runs, abort checks, validate before running) are sent to the client when it connects. Clients add them to the model's context.
• Prompt. acm-groovy-script returns the full guide.
• Resources. The guide and its references are available as acm://skill/SKILL.md, acm://skill/references/api.md (every ACM variable, class and method, generated from the ACM source), acm://skill/references/scripts.md and the script templates under acm://skill/templates/.

Example

Ask the agent something like:

Use ACM to count how many wknd/components/teaser components are under /content/wknd/us/en.

It calls acm_health, then validates and runs a script such as:

boolean canRun() {

return conditions.always() }

void doRun() { def sql = "SELECT * FROM [nt:base] AS n WHERE ISDESCENDANTNODE(n, '/content/wknd/us/en') AND n.[sling:resourceType] = 'wknd/components/teaser'" def count = 0 repo.queryRaw(sql).forEach { resource -> context.checkAborted() count++ } out.info("Found ${count} instance(s)") }

Permissions

ACM checks access at three levels. The user behind the credentials needs jcr:read on each:

1. the API node under /apps/acm/api;
2. the feature node under /apps/acm/feature;
3. the script path under /conf/acm/settings/script.

By default only administrator