This project is inspried from indrasishbanerjee/aem-mcp-server git repo

AEM MCP Server (aem-mcp-server)

MIT License Node.js CI AEM Compatible TypeScript MCP Protocol

AEM MCP Server is a comprehensive, production-ready Model Context Protocol (MCP) server for Adobe Experience Manager (AEM). It provides 40+ robust REST/JSON-RPC API methods for complete content, component, asset, and template management, with advanced integrations for AI, chatbots, and automation workflows. This project is designed for AEM developers, content teams, and automation engineers who want to manage AEM programmatically or via natural language interfaces.

Overview

Modern, TypeScript-based AEM MCP server
REST/JSON-RPC API for AEM content, component, and asset operations
AI/LLM integration (OpenAI, Anthropic, Ollama, custom HTTP APIs)
Production-ready, modular, and extensible

Features

🚀 Core Capabilities (40+ Methods)

Page Operations (10 methods)

Page Lifecycle: Create, delete, activate/deactivate pages with proper template integration
Content Management: Get page content, properties, text extraction, and image management
Page Discovery: List pages with depth control, pagination, and filtering
Publishing: Activate/deactivate pages with tree operations

Component Operations (7 methods)

Component CRUD: Create, update, delete, and validate components
Bulk Operations: Update multiple components with validation and rollback support
Component Discovery: Scan pages to discover all components and their properties
Image Management: Update image paths with verification

Asset Operations (6 methods)

DAM Management: Upload, update, delete assets in AEM DAM
Metadata Operations: Get and update asset metadata
File Processing: Support for multiple file types with MIME type detection
Publishing: Activate or deactivate assets for the publish environment

Search & Query Operations (3 methods)

Advanced Search: QueryBuilder integration with fulltext search
JCR Queries: Execute JCR SQL2-style queries with security validation
Enhanced Page Search: Intelligent search with fallback strategies

Template Operations (2 methods)

Template Discovery: Get available templates for sites and paths
Template Analysis: Detailed template structure and metadata extraction

Site & Localization (3 methods)

Multi-site Management: Fetch sites, language masters, and available locales
Localization Support: Manage content across different languages and regions

Replication & Publishing (2 methods)

Content Replication: Replicate and publish content to selected locales
Unpublishing: Remove content from publish environments

Workflow Operations (2 methods)

Workflow Initiation: Start workflows using models and payloads
Status Tracking: Retrieve workflow instance status by ID

Legacy & Utility Operations (4 methods)

JCR Node Access: Direct node content access and child listing
System Utilities: Method listing and administrative tools

🔧 Technical Features

REST & JSON-RPC APIs: Dual API support for maximum compatibility
Interactive Dashboard: Web-based interface for API exploration and testing
Comprehensive Testing: Built-in test suite with automated issue tracking
Enhanced Error Handling: Structured error responses with retry mechanisms
Security: Authentication, path validation, and safe operation defaults
Performance: Connection pooling, caching, and optimized queries

Quick Start

Prerequisites

Node.js 18+
Access to an AEM instance (local or remote)

Installation

cd clone npm install

Build

npm run build

Run (Production)

npm start

Run (Development, hot reload)

npm run dev

Usage Examples

JSON-RPC API Examples

1. List all pages under a path

curl -u admin:admin \ -X POST http://localhost:3001/mcp \ -H 'Content-Type: application/json' \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "listPages", "params": { "siteRoot": "/content/mysite", "depth": 2, "limit": 10 } }'

2. Create a new page with template

curl -u admin:admin \ -X POST http://localhost:3001/mcp \ -H 'Content-Type: application/json' \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "createPage", "params": { "parentPath": "/content/mysite/en", "title": "New Product Page", "template": "/conf/mysite/settings/wcm/templates/page-template" } }'

3. Update a component property

curl -u admin:admin \ -X POST http://localhost:3001/mcp \ -H 'Content-Type: application/json' \ -d '{ "jsonrpc": "2.0", "id": 3, "method": "updateComponent", "params": { "componentPath": "/content/mysite/en/home/jcr:content/root/container/text", "properties": { "text": "Updated content", "textIsRich": true } } }'

4. Search for content

curl -u admin:admin \ -X POST http://localhost:3001/mcp \ -H 'Content-Type: application/json' \ -d '{ "jsonrpc": "2.0", "id": 4, "method": "searchContent", "params": { "type": "cq:Page", "fulltext": "product", "path": "/content/mysite", "limit": 20 } }'

5. Upload an asset to DAM

curl -u admin:admin \ -X POST http://localhost:3001/mcp \ -H 'Content-Type: application/json' \ -d '{ "jsonrpc": "2.0", "id": 5, "method": "uploadAsset", "params": { "parentPath": "/content/dam/mysite/images", "fileName": "hero-image.jpg", "fileContent": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...", "mimeType": "image/jpeg", "metadata": { "dc:title": "Hero Image", "dc:description": "Main hero image for homepage" } } }'

6. Start a workflow

curl -u admin:admin \ -X POST http://localhost:3001/mcp \ -H 'Content-Type: application/json' \ -d '{ "jsonrpc": "2.0", "id": 6, "method": "startWorkflow", "params": { "modelId": "/var/workflow/models/publish-page", "payloadPath": "/content/mysite/en", "title": "Publish Page" } }'

7. Check workflow status

curl -u admin:admin \ -X POST http://localhost:3001/mcp \ -H 'Content-Type: application/json' \ -d '{ "jsonrpc": "2.0", "id": 7, "method": "getWorkflowStatus", "params": { "workflowId": "test-workflow-123" } }'

REST API Examples

1. Get all available methods

curl -u admin:admin http://localhost:3001/api/methods

2. Get method details

curl -u admin:admin http://localhost:3001/api/methods/createPage

3. Execute method via REST

curl -u admin:admin \ -X POST http://localhost:3001/api/methods/listPages \ -H 'Content-Type: application/json' \ -d '{ "siteRoot": "/content/mysite", "depth": 1, "limit": 10 }'

4. Start a workflow

curl -u admin:admin \ -X POST http://localhost:3001/api/methods/startWorkflow \ -H 'Content-Type: application/json' \ -d '{ "modelId": "/var/workflow/models/publish-page", "payloadPath": "/content/mysite/en", "title": "Publish Page" }'

5. Get workflow status

curl -u admin:admin \ -X POST http://localhost:3001/api/methods/getWorkflowStatus \ -H 'Content-Type: application/json' \ -d '{ "workflowId": "test-workflow-123" }'

Method Categories and Examples

Page Operations

createPage - Create pages with proper template integration
deletePage - Remove pages with force option
listPages - List pages with depth and pagination
getPageContent - Extract complete page content
getPageProperties - Get page metadata and properties
activatePage / deactivatePage - Publish/unpublish pages
getAllTextContent / getPageTextContent - Extract text content
getPageImages - Extract image references

Component Operations

validateComponent - Validate component changes before applying
updateComponent - Update component properties with verification
scanPageComponents - Discover all components on a page
createComponent - Add new components to pages
deleteComponent - Remove components
updateImagePath - Update image component references
bulkUpdateComponents - Update multiple components atomically

Asset Operations

uploadAsset - Upload files to DAM with metadata
updateAsset - Update asset metadata and content
deleteAsset - Remove assets from DAM
getAssetMetadata - Retrieve asset metadata
activateAsset - Publish assets to the publish environment
deactivateAsset - Unpublish assets from the publish environment

Search Operations

searchContent - Query Builder search with flexible parameters
executeJCRQuery - Execute JCR queries (QueryBuilder wrapper)
enhancedPageSearch - Intelligent page search with fallbacks

Template Operations

getTemplates - List available templates for sites
getTemplateStructure - Get detailed template structure

Site & Localization

fetchSites - Get all available sites
fetchLanguageMasters - Get language masters for sites
fetchAvailableLocales - Get available locales

Workflow Operations

startWorkflow - Start workflows using a model and payload path
getWorkflowStatus - Retrieve workflow instance status by ID

Interactive Dashboard

Access the web dashboard at http://localhost:3001/dashboard for:

Interactive method testing
Parameter validation
Response visualization
API documentation
Batch testing capabilities

Configuration

Environment Variables

Create a .env file in the project root with the following (edit as needed):

AEM_HOST=http://localhost:4502 AEM_SERVICE_USER=admin AEM_SERVICE_PASSWORD=admin MCP_PORT=8080 GATEWAY_PORT=3001 MCP_USERNAME=admin MCP_PASSWORD=admin

MCP Client Configuration

Sample for AI-based code editors or custom clients:

{ "mcpServers": { "aem-mcp": { "command": "node", "args": [ "absolute path to dist/mcp-server.js" ] } } }

Advanced Configuration Options

# Optional: Advanced AEM Configuration AEM_SITES_ROOT=/content AEM_ASSETS_ROOT=/content/dam AEM_TEMPLATES_ROOT=/conf AEM_XF_ROOT=/content/experience-fragments AEM_PUBLISHER_URLS=http://localhost:4503 AEM_DEFAULT_AGENT=publish AEM_ALLOWED_COMPONENTS=text,image,hero,button,list,teaser,carousel AEM_QUERY_MAX_LIMIT=100 AEM_QUERY_DEFAULT_LIMIT=20 AEM_QUERY_TIMEOUT=30000 AEM_MAX_DEPTH=5 # Optional: AI Integration (if needed) # OPENAI_API_KEY=your-openai-key # TELEGRAM_BOT_TOKEN=your-telegram-bot-token

API & Client Usage

REST/JSON-RPC: Exposes all AEM operations via HTTP endpoints
Supported Operations: Page/asset CRUD, component validation/update, search, rollout, publish, text/image extraction, and more
AI/LLM: Send natural language commands to the server (via API or Telegram)
Telegram Bot: Connect your bot using TELEGRAM_BOT_TOKEN and chat with your AEM instance

AI IDE Integration (Cursor, Cline, etc.)

AEM MCP Server is compatible with modern AI IDEs and code editors that support MCP protocol, such as Cursor and Cline.

How to Connect:

Install and run the AEM MCP Server as described above.
Configure your IDE to connect to the MCP server. Example for Cursor/Cline:
- Open your IDE's MCP server settings.
- Add a new server with:
  - Type: Custom MCP
  - Command: node
  - Args: ["/absolute/path/to/dist/mcp-server.js"]
  - Port: 8080 (or as configured)
  - Auth: Use MCP_USERNAME/MCP_PASSWORD from your .env
Restart your IDE and connect. The IDE will now be able to:
- List, search, and manage AEM content
- Run MCP methods (CRUD, search, rollout, etc.)
- Use AI/LLM features if enabled

Custom MCP Clients

You can build your own MCP client in any language that supports HTTP/JSON-RPC.
See the Usage Examples for API call patterns.
Authenticate using basic auth (MCP_USERNAME/MCP_PASSWORD).
All MCP methods are available via the /api endpoint.

Security

Auth required for all operations (see MCP_USERNAME/MCP_PASSWORD)
Environment-based configuration for safe deployment
All destructive operations require explicit parameters and validation

Project Structure

src/ — TypeScript source code
dist/ — Compiled JS output

Integrations

AI/LLM: OpenAI, Anthropic, Ollama, custom HTTP APIs

Troubleshooting

Common Issues

Connection Issues

# Test AEM connection curl -u admin:admin http://localhost:4502/libs/granite/core/content/login.html # Check server health curl http://localhost:3001/health

Authentication Problems

Verify AEM credentials in .env file
Check MCP_USERNAME and MCP_PASSWORD for API access
Ensure AEM user has sufficient permissions

Page Creation Issues

Empty pages without jcr:content: Use proper template parameter
Pages not visible in Author: Ensure template exists and is valid
Template not found: Verify template path and permissions

Component Update Failures

Component not found: Verify component path exists
Update failed: Check component properties and validation
Permission denied: Ensure user has write access

Performance Optimization

Use pagination with limit parameter for large result sets
Set appropriate depth values for page listing
Configure AEM_QUERY_TIMEOUT for slow queries
Use bulk operations for multiple component updates

Debugging

# Enable debug logging DEBUG=aem-mcp:* npm run dev # Check detailed health status curl http://localhost:3001/health # List all available methods curl -u admin:admin http://localhost:3001/api/methods

Common Use Cases

Content Migration

// 1. List source pages const pages = await listPages({ siteRoot: '/content/source', depth: 3 }); // 2. Create target pages with templates for (const page of pages.data.pages) { await createPage({ parentPath: '/content/target', title: page.title, template: '/conf/target/settings/wcm/templates/page' }); } // 3. Copy components const components = await scanPageComponents({ pagePath: sourcePage }); for (const component of components.data.components) { await createComponent({ pagePath: targetPage, componentType: component.resourceType, properties: component.properties }); }

Bulk Content Updates

// Update multiple text components const updates = [ { componentPath: '/content/site/page1/jcr:content/text1', properties: { text: 'Updated content 1' } }, { componentPath: '/content/site/page2/jcr:content/text2', properties: { text: 'Updated content 2' } } ]; await bulkUpdateComponents({ updates, validateFirst: true, continueOnError: false });

Asset Management Workflow

// 1. Upload assets await uploadAsset({ parentPath: '/content/dam/project', fileName: 'hero.jpg', fileContent: base64Content, metadata: { 'dc:title': 'Hero Image' } }); // 2. Update page to use new asset await updateComponent({ componentPath: '/content/site/home/jcr:content/hero', properties: { fileReference: '/content/dam/project/hero.jpg' } }); // 3. Publish changes await activatePage({ pagePath: '/content/site/home' });

Search and Discovery

// Find pages by content const results = await searchContent({ type: 'cq:Page', fulltext: 'product launch', path: '/content/mysite' }); // Get detailed page information for (const result of results.data.results) { const content = await getPageContent({ pagePath: result.path }); const components = await scanPageComponents({ pagePath: result.path }); }

API Reference

Authentication

All API endpoints require HTTP Basic Authentication:

Authorization: Basic base64(username:password)

Response Format

All responses follow this structure:

{ "success": true, "operation": "methodName", "timestamp": "2024-01-01T00:00:00.000Z", "data": { // Method-specific response data } }

Error Handling

Error responses include structured information:

{ "success": false, "operation": "methodName", "timestamp": "2024-01-01T00:00:00.000Z", "error": { "code": "ERROR_CODE", "message": "Human readable error message", "details": {}, "recoverable": true, "retryAfter": 5000 } }

Error Handling Best Practices

The AEM MCP Server follows REST API best practices by returning HTTP 200 status codes with structured error information in the response body. This approach provides several benefits:

Consistent Response Format: All responses, whether successful or not, follow the same JSON structure
Detailed Error Information: Error responses include specific codes, messages, and details
Client-Side Processing: Clients can easily parse and handle errors programmatically
Recoverable vs. Fatal Errors: The recoverable flag indicates if retrying might succeed
Retry Guidance: When appropriate, retryAfter suggests a wait time before retrying

Example Error Handling in Client Code:

async function callMcpMethod(method, params) { const response = await fetch(`/api/methods/${method}`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(params) }); const result = await response.json(); if (!result.success) { // Handle error based on error code and details console.error(`Error in ${method}:`, result.error.message); if (result.error.recoverable && result.error.retryAfter) { // Implement retry logic console.log(`Retrying after ${result.error.retryAfter}ms`); await new Promise(resolve => setTimeout(resolve, result.error.retryAfter)); return callMcpMethod(method, params); // Recursive retry } throw new Error(`${result.error.code}: ${result.error.message}`); } return result.data; }

Common Error Codes:

Error Code	Description	Recoverable
`INVALID_PARAMS`	Missing or invalid parameters	No
`PATH_NOT_FOUND`	Specified path does not exist	No
`PERMISSION_DENIED`	Insufficient permissions	No
`TEMPLATE_NOT_FOUND`	Template does not exist	No
`COMPONENT_NOT_FOUND`	Component does not exist	No
`NETWORK_ERROR`	Connection to AEM failed	Yes
`TIMEOUT`	Operation timed out	Yes
`RESOURCE_LOCKED`	Resource is locked by another process	Yes
`SERVER_BUSY`	Server is under heavy load	Yes
`VALIDATION_FAILED`	Content validation failed	No

License

MIT

MCP Badge

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

A comprehensive Model Context Protocol server for Adobe Experience Manager that provides 35+ REST/JSON-RPC API methods for complete content, component, asset, and template management. Enables AI-powered AEM automation through natural language interfaces with support for page operations, component CRUD, asset management, and publishing workflows.