Aem MCP Server

AEM MCP Server (aem-mcp-server)

AEM MCP Server is a full-featured Model Context Protocol (MCP) server for Adobe Experience Manager (AEM). It provides a simple integration with any AI Agent. This project is designed for non-technical persons who want to manage AEM via natural language.

---

Overview

• Manage your AEM instance with natural language — content, components, assets, workflows
• Works with any MCP-compatible client:
• AI IDEs — Cursor, VS Code + Copilot, Windsurf, Cline, JetBrains AI Assistant, Zed
• CLI agents — Claude Code, GitHub Copilot CLI, Gemini CLI, Amazon Q CLI
• Chat & desktop apps — Claude Desktop, ChatGPT Desktop, Goose
• Supports both AEMaaCS and self-hosted AEM instances
• Two transport modes — stdio via npx (recommended, zero install) and streamable HTTP

---

Quick Start

Prerequisites

• Node.js 20.19.0+ || 22.12.0+ || 23+
• Access to an AEM instance (local or remote)

Stdio Transport (recommended)

No installation needed — the AI agent downloads and spawns the process automatically via npx.

Add to your project's MCP config (.mcp.json, .vscode/mcp.json, .cursor/mcp.json, etc.):

{

"mcpServers": { "AEM": { "command": "npx", "args": ["-y", "aem-mcp-server", "-t", "stdio", "-H", "http://localhost:4502", "-u", "admin", "-p", "admin"] } } }

Secrets: Since MCP config files are typically committed to the repo, avoid hardcoding credentials. Use your client's env var syntax instead:

| Client | Syntax |

|---|---|

| Claude Code (.mcp.json) | ${AEM_PASSWORD} or ${AEM_PASSWORD:-admin} |

| VS Code / Copilot | ${input:aem-password} (prompts securely) or envFile |

| Cursor | ${env:AEM_PASSWORD} |

Example with env var references (Claude Code):

`json

{

"mcpServers": {

"AEM": {

"command": "npx",

"args": ["-y", "aem-mcp-server", "-t", "stdio", "-H", "${AEM_HOST:-http://localhost:4502}", "-u", "${AEM_USER:-admin}", "-p", "${AEM_PASSWORD:-admin}"]

}

}

}

`

Streamable HTTP Transport (alternative)

For scenarios where you need a persistent server (shared team server, multiple clients connecting simultaneously, etc.), install globally and start the server manually:

npm install aem-mcp-server -g

aem-mcp -H=http://localhost:4502 -u=admin -p=admin

Then point your AI agent to the URL:

{

"mcpServers": { "AEM": { "url": "http://127.0.0.1:8502/mcp" } } }

Configuration

Options:

--version Show version number [boolean] -H, --host [string] [default: "http://localhost:4502"] -u, --user [string] [default: "admin"] -p, --pass [string] [default: "admin"] -i, --id clientId [string] [default: ""] -s, --secret clientSecret [string] [default: ""] -m, --mcpPort [number] [default: 8502] -t, --transport Transport mode: http (default) or stdio [string] [choices: "http", "stdio"] [default: "http"] -I, --instances Named AEM instances: "local:http://localhost:4502:admin:admin ,qa:https://qa.example.com:user:pass" [string] [default: ""] -h, --help Show help [boolean]

Authentication:

• For AEMaaCS, use clientId and clientSecret for OAuth S2S authentication. More info.
• For self-hosted AEM, use user/pass. Default credentials are admin:admin.

Multi-instance: Connect to multiple AEM instances simultaneously:

aem-mcp --instances "author:http://localhost:4502:admin:admin,publish:http://localhost:4503:admin:admin"

All tools will get an instance parameter to target a specific instance.

---

Features

• 57 MCP Tools covering pages, components, assets, workflows, content fragments, and experience fragments
• MCP Resources — agents discover components, sites, templates, and workflow models upfront via resources/list, eliminating discovery roundtrips
• Tool Annotations — every tool tagged with group, readOnly, and complexity so agents can make smarter tool selection decisions
• Response Verbosity — verbosity parameter (summary/standard/full) on content-reading tools strips JCR internals and truncates long text
• Actionable Errors — error responses include suggestion and alternatives fields for self-healing agent workflows
• Component Operations: Update, scan, add, convert, and bulk-manage AEM components (including Experience Fragments)
• Content & Experience Fragments: Full CRUD + variation management for both CF and XF, plus server-side JSON-string field merging (manageContentFragment action mergeJsonField) for CFs that store a whole key→value map inside one JSON-encoded field
• Advanced Search: QueryBuilder, fulltext, fuzzy, and enhanced page search
• Replication & Workflows: Publish/unpublish content, start/advance/delegate workflow stages
• Text & Image Extraction: Extract all text and images from pages, including fragments
• Template & Structure Discovery: List templates, analyze page/component structure
• Multi-instance: Connect to multiple AEM instances simultaneously; tools and resources are instance-aware
• Security: Basic auth and OAuth S2S, environment-based config, safe operation defaults

---

Usage

Once configured in your AI IDE, just ask in natural language:

List all components on MyPage

Merging into a JSON-string field

Some Content Fragments store an entire key→value map inside a single field as a JSON-encoded string. To upsert a few keys without round-tripping the whole blob, use the mergeJsonField action — the read-merge-write happens server-side:

{

"action": "mergeJsonField", "fragmentPath": "/content/dam/ /.../labels", "field": "CFMValue", // the field holding the JSON string "jsonPointer": "/0/content/0/value", // RFC-6901 pointer to the object to merge into ("" = field root) "merge": { "search": "Search", "clear_search": "Clear search" }, "variation": "master" // default: master }

New keys are added, existing keys overwritten (deep-merge), and untouched keys preserved. The response reports the keys added/overwritten and the before/after key count at the pointer.

MCP Resources

The server exposes read-only MCP resources so agents can discover AEM catalogs without tool calls:

Resources return summary data only. In multi-instance mode, each instance gets its own set of resource URIs.

API Documentation

For detailed API documentation, please refer to the API Docs.

Similar Projects

1. https://github.com/easingthemes/aem-mcp-server (Used as a base for this project)
2. https://github.com/indrasishbanerjee/aem-mcp-server (Used as a base for #1)
3. https://www.npmjs.com/package/@myea/aem-mcp-handler (Looks like an original source of #2)