AEM MCP Server (Hybrid Edition)

A Model Context Protocol (MCP) server for Adobe Experience Manager (AEM) that combines the clean architecture of the implementation with the comprehensive features of the Current implementation.

What's New in Hybrid Edition

Features

Content Management

• Query JCR content using QueryBuilder API
• Read, create, update, and delete nodes
• Move and copy nodes with reference updates
• Execute JCR SQL2/XPath queries
• Search pages by title or content

Page Management

• Create pages with automatic template selection
• Update page properties and metadata
• Delete pages with confirmation
• Move and copy pages with reference updates
• Page tree navigation and hierarchy
• List pages with pagination
• Content extraction: text and images
• Publishing: activate/deactivate pages
• Replication status checking

Component Management

• List and search components
• Get component details
• Add components to pages
• Update component properties
• Delete components
• Scan page components
• Bulk update components
• Find component usage across site
• Update image paths
• Client library management

Asset Management (DAM)

• Search assets by name, metadata, or type
• Get asset metadata
• Create asset folders
• Update asset metadata and tags
• Get asset renditions
• Upload assets (base64)
• Tag assets

Workflow Management

• Start workflow instances
• List active/completed workflows
• Get workflow status
• Complete workflow steps
• Cancel, suspend, resume workflows
• List workflow models

Version Control

• Get version history
• Create versions with labels
• Restore previous versions
• Compare versions
• Delete versions

System Administration

• System information
• Health checks
• OSGi bundle management
• Replication agent monitoring
• User and group listing
• Query performance analysis

Installation

This server is published on npm as aem-mcp-server-globant. No clone, build, or local Node project is required — your MCP client runs it on demand via npx. The only thing you provide is your own AEM URL and credentials.

Prerequisites

• Node.js 18+ (so npx is available)
• Access to an AEM instance

Add to your MCP client

Add the following to your client's MCP configuration (e.g. Claude Desktop's claude_desktop_config.json, .cursor/mcp.json, or a project .mcp.json), then restart the client:

{
  "mcpServers": {
    "aem": {
      "command": "npx",
      "args": ["-y", "aem-mcp-server-globant"],
      "env": {
        "AEM_BASE_URL": "https://your-aem-host:4502",
        "AEM_USERNAME": "your-user",
        "AEM_PASSWORD": "your-password"
      }
    }
  }
}

Claude Code (one command, no JSON editing)

claude mcp add aem \
  -e AEM_BASE_URL=https://your-aem-host:4502 \
  -e AEM_USERNAME=your-user \
  -e AEM_PASSWORD=your-password \
  -- npx -y aem-mcp-server-globant

That's it — npx downloads and caches the package automatically on first run.

From source (for development)

Only needed if you want to modify the server:

1. Install dependencies:

cd aem-mcp-server-zarza
npm install

2. Build the TypeScript:

npm run build

Configuration

Set the following environment variables:

| Variable | Description | Required | |----------|-------------|----------| | AEM_BASE_URL | AEM instance URL (e.g., http://localhost:4502) | Yes | | AEM_USERNAME | AEM username | Yes | | AEM_PASSWORD | AEM password | Yes | | AEM_TIMEOUT | Request timeout in ms (default: 30000) | No | | AEM_INSECURE | Ignore SSL errors (not recommended) | No |

Example .env file

AEM_BASE_URL=http://localhost:4502
AEM_USERNAME=admin
AEM_PASSWORD=admin
AEM_TIMEOUT=30000

Claude Desktop Configuration

Config file location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%/Claude/claude_desktop_config.json

Use the npx configuration shown in Installation above — no local path required.

Running from source instead

If you built the server locally (see From source), point the client at your compiled entry file:

{
  "mcpServers": {
    "aem": {
      "command": "node",
      "args": ["/path/to/aem-mcp-server-zarza/dist/index.js"],
      "env": {
        "AEM_BASE_URL": "http://localhost:4502",
        "AEM_USERNAME": "admin",
        "AEM_PASSWORD": "admin"
      }
    }
  }
}

Available Tools (45+)

Content Tools

• aem_query - Query content using QueryBuilder
• aem_getNode - Get node details
• aem_searchContent - Search content
• aem_createNode - Create JCR nodes
• aem_updateNode - Update node properties
• aem_deleteNode - Delete nodes
• aem_moveNode - Move/rename nodes
• aem_copyNode - Copy nodes
• aem_listChildren - List child nodes
• aem_executeJCRQuery - Execute SQL2/XPath queries

Page Tools

• aem_createPage - Create pages with auto-template
• aem_updatePage - Update page properties
• aem_deletePage - Delete pages
• aem_getPage - Get page details
• aem_listPages - List pages with pagination
• aem_getPageTree - Page hierarchy
• aem_movePage - Move pages
• aem_copyPage - Copy pages
• aem_listTemplates - List templates
• aem_getTemplateStructure - Template details
• aem_getPageContent - Full page content
• aem_getPageTextContent - Extract text
• aem_getPageImages - Extract images
• aem_activatePage - Publish pages
• aem_deactivatePage - Unpublish pages
• aem_getReplicationStatus - Check replication
• aem_fetchSites - List sites
• aem_searchPages - Search pages

Component Tools

• aem_listComponents - List components
• aem_searchComponents - Search components
• aem_getComponent - Component details
• aem_addComponent - Add to page
• aem_updateComponent - Update properties
• aem_deleteComponent - Remove from page
• aem_scanPageComponents - Scan page
• aem_bulkUpdateComponents - Bulk operations
• aem_findComponentUsage - Find usages
• aem_updateImagePath - Update images
• aem_listComponentGroups - Component groups
• aem_listClientlibs - Client libraries
• aem_getContainerStructure - Container structure

Asset Tools

• aem_searchAssets - Search DAM
• aem_getAsset - Asset metadata
• aem_listAssets - List folder assets
• aem_getAssetFolders - Folder structure
• aem_createAssetFolder - Create folders
• aem_updateAssetMetadata - Update metadata
• aem_deleteAsset - Delete assets
• aem_getAssetRenditions - List renditions
• aem_tagAsset - Tag assets
• aem_getTags - List tags
• aem_uploadAsset - Upload files

Workflow Tools

• aem_startWorkflow - Start workflows
• aem_listActiveWorkflows - Active workflows
• aem_getWorkflowStatus - Workflow status
• aem_completeWorkflowStep - Complete steps
• aem_cancelWorkflow - Cancel workflows
• aem_suspendWorkflow - Suspend workflows
• aem_resumeWorkflow - Resume workflows
• aem_getWorkflowModels - List models

Version Tools

• aem_getVersionHistory - Version history
• aem_createVersion - Create versions
• aem_restoreVersion - Restore versions
• aem_compareVersions - Compare versions
• aem_deleteVersion - Delete versions

System Tools

• aem_getSystemInfo - System information
• aem_getStatus - AEM status
• aem_healthCheck - Health checks
• aem_listBundles - OSGi bundles
• aem_getBundle - Bundle details
• aem_listReplicationAgents - Replication agents
• aem_getReplicationQueue - Queue status
• aem_listUsers - List users
• aem_listGroups - List groups
• aem_listPackages - CRX packages
• aem_listSlingModels - Sling Models
• aem_explainQuery - Query analysis
• aem_slowQueries - Slow queries

MCP Resources

The server exposes these MCP resources:

• aem://content - Content repository tree
• aem://dam - DAM folder structure
• aem://system - System information
• aem://components - Component library
• aem://templates - Page templates
• aem://{path} - Any JCR path

Architecture

aem-mcp-server/
├── src/
│   ├── index.ts              # Main entry point with Resource + Tool handlers
│   ├── tools/
│   │   ├── content.ts        # Content operations (10 tools)
│   │   ├── pages.ts          # Page operations (17 tools)
│   │   ├── assets.ts         # DAM operations (11 tools)
│   │   ├── components.ts     # Component operations (14 tools)
│   │   ├── workflows.ts      # Workflow operations (7 tools)
│   │   ├── versions.ts       # Version control (5 tools)
│   │   └── system.ts         # System admin (14 tools)
│   ├── utils/
│   │   └── aem-client.ts     # Enhanced native fetch client
│   └── types/
│       └── index.ts          # Comprehensive TypeScript types
├── dist/                     # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

Error Handling

The hybrid edition includes comprehensive error handling:

• Structured error codes: INVALID_PATH, PATH_NOT_FOUND, AUTHENTICATION_ERROR, etc.
• Retry logic: Automatic retry for transient network errors
• Fallback methods: Alternative APIs when primary fails
• Detailed messages: Clear error descriptions with context

Development

Build

npm run build

Watch Mode

npm run dev

Type Checking

npm run typecheck

Linting

npm run lint

Hybrid Design Principles

1. Clean Architecture: Tools organized by domain in separate files
2. Native Fetch: Modern HTTP client without axios dependency
3. Resource Support: MCP resources for content browsing
4. Comprehensive Features: All operations from both original implementations
5. Type Safety: Full TypeScript coverage
6. Error Resilience: Robust error handling and recovery

adobe-aem-mcp