AEM MCP Server

How to use

You connect to the server from an MCP client or your own code over HTTP or via a local (stdio) MCP runtime. Use the HTTP endpoint for remote or local testing, and you can also start a local MCP server process and connect with a code editor or custom client using a local channel.

How to install

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

# Installation from project root
cd clone
npm install

# Build the server
npm run build

# Run in production
npm start

# Optional: run in development with hot reload
npm run dev

Configuration and usage notes

Configure the environment and MCP client to connect securely. Create a .env file in your project root with the following values (adjust 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

Security and access

All MCP operations require authentication. Use the MCP username and password you define in the environment to access endpoints. Ensure your AEM credentials have the necessary permissions for content, assets, and templates you intend to manage.

Troubleshooting

Common issues include connectivity to AEM, authentication problems, or permission errors. Validate your .env values, confirm AEM is reachable, and check that the MCP user has rights to the targeted paths and templates.

Examples of capabilities (tools you can call)

The server exposes a wide range of operations. Typical actions you perform include page lifecycle management, component updates, asset handling, search, and template discovery. You can orchestrate batch updates, scan pages for components, and publish or retract content across locales.

AI IDE integration and clients

You can connect modern AI-enabled editors or custom clients via MCP. Configure your IDE to connect to the MCP server by pointing it to the runtime or HTTP endpoint and using your MCP credentials. The IDE can list, search, and execute MCP methods, and you can leverage AI features if enabled.

License and licensing notes

This project is licensed under AGPL-V3. For commercial use in enterprise environments, a paid license is required.

Examples of common workflows

Content migration, bulk updates, asset workflows, and search-driven content discovery are common patterns. You can list pages, create or update pages and components, upload assets, run searches, and publish content across sites and locales.

Notes on server endpoints and operation

HTTP endpoint for MCP: use the server URL that exposes the MCP API at /mcp for operations. REST and JSON-RPC interfaces are available to cover different client preferences.

Security best practices

Use strong credentials for MCP access, constrain network access to trusted hosts, and validate inputs for destructive operations. Enable pagination and safe operation defaults to minimize impact on large content sets.

Project structure and integrations

The server is built with TypeScript, exposes REST and JSON-RPC APIs, and integrates with AI providers and a Telegram bot for chat-based management. It offers a dashboard for API exploration and testing.

Contributing and support

Contributions are welcome. Open issues or pull requests to suggest bug fixes, new integrations, or documentation improvements. For customizations and enterprise deployments, you can discuss requirements via your preferred communication channel.

What you get with MCP server at a glance

- Modern TypeScript-based MCP server for AEM - REST and JSON-RPC APIs for pages, components, assets, and templates - AI/LLM integrations and Telegram bot for conversational management - Production-ready, modular, and extensible design - Interactive dashboard for testing and exploration

FAQ and tips

If you encounter template or path issues, verify the exact template paths and permissions. For authentication problems, confirm MCP credentials and ensure the AEM user has the necessary rights.

Notes on environment variables and MCP client config

You can configure an MCP client to connect to your server using the following example. If you are using an IDE or a code editor, specify the runtime path to the MCP server and provide authentication details in your client configuration.

Internal tooling and tooling availability

The server exposes a range of endpoints and methods for content, asset, and template management, including search, replication, and localization workflows. All methods return structured results with clear error information to aid automation.

Notes on licensing

AGPL-V3 license applies. For commercial deployments, ensure you have the appropriate license for enterprise use.

listPages

List pages under a site root with depth control and pagination. Useful for discovering site structure.

createPage

Create a new page under a given parent path with a specified template.

updateComponent

Update properties of a component at a given path, with validation and safety checks.

uploadAsset

Upload an asset to the AEM DAM with metadata and optional MIME type detection.

searchContent

Perform a flexible content search with type, path, and fulltext filters.

activatePage

Publish or activate a page to make it available in publish environments.

scanPageComponents

Scan a page to discover all components and their properties.

getTemplates

List templates available for sites and paths.

getPageContent

Retrieve the complete content of a page, including properties and text.

getAssetMetadata

Fetch metadata for a given DAM asset.