How do I use AEM Assets MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@AEM Assets MCP Server Search for assets related to 'Electric Vehicle' and show their details." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

AEM Assets MCP Server

A Model Context Protocol (MCP) server for Adobe Experience Manager (AEM) Assets Author API built with Python and FastAPI. Can be deployed to Vercel (Phase 1) or Google Cloud Run (Phase 2) and used with ChatGPT.

🚀 Features

This MCP server provides tools to interact with AEM Assets:

List folders - Browse folders in your AEM Assets repository
List published assets - Find all assets that have been published
Search assets - Search for assets by keywords (e.g., "Electric Vehicle")
List assets by folder - Get all assets within a specific folder
Bulk update metadata - Update metadata for all assets in a folder
List assets by creator - Find assets uploaded by a specific user
Get asset details - Retrieve detailed information about a specific asset

📋 Prerequisites

General Requirements

Adobe Experience Manager Assets Author API Access
- AEM base URL
- OAuth Server-to-Server credentials:
  - Client ID (API Key)
  - Client Secret
  - Scopes
- See GET_CREDENTIALS.md for how to obtain these
Python 3.11+

Phase 1 Requirements (Vercel)

Vercel account
ChatGPT Plus/Pro (to use MCP servers)

Phase 2 Requirements (Google Cloud Run)

Google Cloud Platform account
gcloud CLI installed
Terraform installed (for infrastructure as code)
Docker installed
GitHub account (for CI/CD)

🛠️ Tech Stack

Python 3.11 - Core language
FastAPI - Modern async web framework
HTTPX - Async HTTP client
Pydantic - Data validation
OAuth Server-to-Server - Automatic token refresh
Docker - Containerization
Terraform - Infrastructure as Code
GitHub Actions - CI/CD

📁 Project Structure

. ├── app/ │ ├── __init__.py # Package initialization │ ├── main.py # FastAPI application │ ├── aem_client.py # AEM Assets API client │ └── models.py # Pydantic models ├── terraform/ │ ├── main.tf # Main Terraform configuration │ ├── variables.tf # Terraform variables │ └── terraform.tfvars.example ├── .github/workflows/ │ ├── deploy-cloud-run.yml # Cloud Run deployment │ ├── terraform-apply.yml # Terraform workflow │ └── test.yml # Testing workflow ├── Dockerfile # Docker configuration ├── requirements.txt # Python dependencies ├── vercel.json # Vercel configuration ├── env.example # Environment template └── README.md

🚀 Quick Start

Local Development

Clone the repository:

cd "SC Practice 20260130 - Assets MCP"

Create virtual environment:

python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate

Install dependencies:

pip install -r requirements.txt

Configure environment:

# Option 1: Interactive setup (recommended) ./create-env.sh # Option 2: Manual setup cp env.example .env nano .env # Edit with your AEM credentials

See GET_CREDENTIALS.md for how to get your OAuth credentials.

Run locally:

uvicorn app.main:app --reload

Visit http://localhost:8000 to see the server info.

Docker Development

# Build image docker build -t aem-mcp-server . # Run container docker run -p 8080:8080 \ -e AEM_BASE_URL="your_url" \ -e AEM_ACCESS_TOKEN="your_token" \ -e AEM_ORG_ID="your_org_id" \ -e AEM_CLIENT_ID="your_client_id" \ aem-mcp-server

📦 Phase 1: Deploy to Vercel

See DEPLOYMENT_VERCEL.md for detailed instructions.

Quick steps:

# Install Vercel CLI npm i -g vercel # Deploy vercel # Add environment variables in Vercel dashboard # Deploy to production vercel --prod

Your API will be available at: https://your-project.vercel.app/api/mcp

🏗️ Phase 2: Deploy to Google Cloud Run

See DEPLOYMENT_CLOUDRUN.md for detailed instructions.

Option 1: Using GitHub Actions (Recommended)

Set up GCP and GitHub Secrets
Push to main branch - Automatically deploys
Service URL will be shown in Actions log

Option 2: Using Terraform

cd terraform # Copy and edit variables cp terraform.tfvars.example terraform.tfvars nano terraform.tfvars # Initialize Terraform terraform init # Preview changes terraform plan # Deploy infrastructure terraform apply

Option 3: Manual Docker Deployment

# Build and tag docker build -t gcr.io/YOUR_PROJECT/aem-mcp-server . # Push to Container Registry docker push gcr.io/YOUR_PROJECT/aem-mcp-server # Deploy to Cloud Run gcloud run deploy aem-assets-mcp-server \ --image gcr.io/YOUR_PROJECT/aem-mcp-server \ --platform managed \ --region us-central1 \ --allow-unauthenticated

🔧 Configuration

Environment Variables

Create a .env file with:

# AEM Instance AEM_BASE_URL=https://author-p161901-e1740392.adobeaemcloud.com AEM_API_ENDPOINT=/adobe/assets # OAuth Server-to-Server Credentials AEM_CLIENT_ID=a41e805f8c3042d3bba66ff1c05f1e94 AEM_CLIENT_SECRET=your_client_secret_here AEM_SCOPES=openid,AdobeID,read_organizations,additional_info.projectedProductContext,additional_info.roles # Adobe IMS (usually no need to change) ADOBE_IMS_TOKEN_ENDPOINT=https://ims-na1.adobelogin.com/ims/token/v3

Get AEM Credentials

Quick Setup:

./create-env.sh # Interactive credential setup

Manual Setup:

See GET_CREDENTIALS.md for detailed instructions.

Summary:

Go to Adobe Developer Console
Create/select project
Add "AEM Assets Author API"
Configure "OAuth Server-to-Server" authentication
Copy Client ID and Client Secret
Copy Scopes from the credential page

Key Benefits:

✅ Automatic token refresh (every ~1 hour)
✅ No manual token management
✅ Production-ready authentication
✅ Based on Adobe's OAuth S2S guide

🤖 Connect to ChatGPT

See CHATGPT_SETUP.md for complete integration guide.

Quick summary:

Create Custom GPT in ChatGPT
Add Action with OpenAPI schema
Point to your deployed URL
Test with natural language prompts

💬 Usage Examples

Once connected to ChatGPT:

✅ "List all the folders in the root directory" ✅ "Show me all published assets" ✅ "Find assets related to Electric Vehicle" ✅ "Update all assets in /content/dam/products with jancode: ABCDEFG" ✅ "List all assets uploaded by user@example.com"

🔌 API Reference

Endpoints

GET / - Server information
GET /api/mcp - Server information
POST /api/mcp - Execute MCP tool
GET /health - Health check

Available Tools

1. `list_folders`

{ "tool": "list_folders", "arguments": { "path": "/content/dam" } }

2. `list_published_assets`

{ "tool": "list_published_assets", "arguments": { "limit": 50 } }

3. `search_assets`

{ "tool": "search_assets", "arguments": { "query": "Electric Vehicle", "limit": 100 } }

4. `list_assets_by_folder`

{ "tool": "list_assets_by_folder", "arguments": { "folderPath": "/content/dam/products" } }

5. `bulk_update_metadata`

{ "tool": "bulk_update_metadata", "arguments": { "folderPath": "/content/dam/products", "metadata": { "jancode": "ABCDEFG", "category": "Electronics" } } }

6. `list_assets_by_creator`

{ "tool": "list_assets_by_creator", "arguments": { "createdBy": "user@example.com", "limit": 50 } }

7. `list_all_assets`

{ "tool": "list_all_assets", "arguments": { "path": "/content/dam", "limit": 200 } }

8. `get_asset_details`

{ "tool": "get_asset_details", "arguments": { "assetId": "urn:aaid:aem:12345" } }

🧪 Testing

Manual Testing

# Test health endpoint curl http://localhost:8000/health # Test tool call curl -X POST http://localhost:8000/api/mcp \ -H "Content-Type: application/json" \ -d '{ "tool": "list_folders", "arguments": {"path": "/"} }'

Run Tests (when available)

pytest tests/ -v

🔐 Security

✅ Environment variables for credentials
✅ CORS configured for API access
✅ Secret Manager for Cloud Run
✅ Service Account with minimal permissions
✅ HTTPS enforced

Important:

Never commit .env or terraform.tfvars
Rotate AEM tokens regularly
Use Workload Identity Federation for GitHub Actions
Restrict Cloud Run access as needed

🐛 Troubleshooting

Common Issues

Import errors in FastAPI:

pip install --upgrade -r requirements.txt

Docker build fails:

# Check Docker is running docker ps # Build with no cache docker build --no-cache -t aem-mcp-server .

Terraform errors:

# Re-initialize cd terraform rm -rf .terraform terraform init

Cloud Run deployment fails:

Check Secret Manager has correct values
Verify service account permissions
Check Artifact Registry has image
Review Cloud Run logs

📚 Additional Documentation

DEPLOYMENT_VERCEL.md - Phase 1 deployment guide
DEPLOYMENT_CLOUDRUN.md - Phase 2 deployment guide
CHATGPT_SETUP.md - ChatGPT integration guide
AEM Assets API Docs

🤝 Contributing

Fork the repository
Create feature branch
Make changes
Test thoroughly
Submit pull request

📄 License

MIT License - See LICENSE file for details

🔗 Resources

💡 Tips

Start with Phase 1 (Vercel) for quick testing
Use Terraform for reproducible infrastructure
Monitor logs in Cloud Run console
Set up alerts for production deployments
Use Secret Manager for all sensitive data

Need Help? Check the documentation files or open an issue on GitHub.