aem-troubleshooting-mcp-server

A read-only Model Context Protocol server for Adobe Experience Manager (AEM). It lets an AI assistant (GitHub Copilot, Claude, VS Code agent mode) triage an AEM 6.5 / AMS instance the way a support engineer would: check OSGi bundles and components, replication queues, Oak indexes and logs, then explain what is wrong and what to do next.

"Why is publishing slow on author?" → the assistant calls aem_health_summary, sees the publish queue is blocked by an item retried 14 times, finds the matching ReplicationException in error.log, and tells you which item to clear instead of clearing the whole queue.

Why

During an AEM incident the first 30 minutes are always the same: open the Felix console, scan bundles, open the replication agents, tail error.log, grep for OutOfMemoryError and traversal warnings, check index definitions. This server packages that runbook as safe, structured tools an assistant can call, so triage is fast, consistent and explainable.

flowchart LR
    U[Engineer] -->|"Why are pages failing to publish?"| H[MCP host<br/>Copilot / Claude / VS Code]
    H <-->|stdio, JSON-RPC| S[aem-troubleshooting-mcp]
    S -->|GET only| C[/system/console<br/>bundles, components, log tailer/]
    S -->|GET only| R[/etc/replication<br/>agents & queues/]
    S -->|GET only| O[/oak:index<br/>/bin/querybuilder.json/]
    S --> A[aem-log-analyzer<br/>14 AEM issue rules]

Related MCP server: MCP IT Ops Server

Tools

Plus a prompt, triage_aem_incident, that walks the assistant through a structured incident runbook.

Safety model

This server is designed to be pointed at real environments without fear:

• Read-only by construction. The HTTP client only issues GET requests and every tool is annotated readOnlyHint: true. There are no tools to clear queues, restart bundles or modify content.

• No secrets in output. Replication agent transportUser/transportPassword are never returned and credentials are stripped from transport URIs. aem_connection_info reports the auth mode, not the password.

• Query guardrails. QueryBuilder searches must be scoped below /content, /conf, /apps, /libs, /etc or /var (at least two levels deep), p.limit must be 1–100 and p.guessTotal is always on, so an assistant can't trigger a repository-wide traversal.

• Bounded responses. Log reads, index definitions and HTTP bodies are size-capped to protect both AEM and the model's context window.

• Clear errors. 401/403/404, login-page redirects, timeouts and unreachable hosts become actionable messages.

Use a dedicated read-only user where possible.

Quick start

Requires Python 3.10+. With uv:

uvx --from git+https://github.com/navi00498/aem-troubleshooting-mcp-server aem-troubleshooting-mcp --version

or with pip, inside a virtualenv on Python 3.10+ (macOS ships 3.9; brew install python@3.12 or uv gets you a newer one):

python3 -m venv .venv && source .venv/bin/activate
pip install git+https://github.com/navi00498/aem-troubleshooting-mcp-server

Configuration is via environment variables:

Try it without AEM

The repo ships a mock AEM author instance with realistic problems planted in it (a blocked replication queue, a bundle stuck in Installed, a failed component, an index with reindex=true, an OutOfMemoryError in the logs):

git clone https://github.com/navi00498/aem-troubleshooting-mcp-server && cd aem-troubleshooting-mcp-server
uv venv && source .venv/bin/activate && uv pip install -e .   # or: python3 -m venv .venv && ... && pip install -e .
python examples/demo_client.py

Connected. 11 read-only tools: aem_connection_info, aem_health_summary, list_bundles, ...

Overall: CRITICAL
  - 2 bundle(s) not active
  - 2 component(s) unsatisfied or failed
  - replication queue 'publish' is blocked (37)
  - error.log: [critical] JVM OutOfMemoryError
  - error.log: [high] Uncaught exceptions while rendering requests (HTTP 500)
  - error.log: [high] Oak queries traversing the repository (missing index)
  - error.log: [high] Replication / content distribution failures
  - error.log: [high] Oak query aborted after hitting the read/traversal limit

Replication 'publish': The first item has been retried 14 times and is blocking the queue. Check the agent log and
the target instance (credentials, disk space, receiving servlet). If the item itself is bad, clear only that item
rather than the whole queue.

Guardrail check (query on '/'): Error executing tool query_content: Path '/' is too broad. ...

To point a real MCP host at the mock, run aem-mock-server --port 4502 in another terminal.

Connect it to your assistant

VS Code (Copilot agent mode) – .vscode/mcp.json:

{
  "inputs": [{ "type": "promptString", "id": "aem-password", "description": "AEM password", "password": true }],
  "servers": {
    "aem": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "git+https://github.com/navi00498/aem-troubleshooting-mcp-server", "aem-troubleshooting-mcp"],
      "env": { "AEM_URL": "http://localhost:4502", "AEM_USER": "admin", "AEM_PASSWORD": "${input:aem-password}" }
    }
  }
}

GitHub Copilot CLI – ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "aem": {
      "type": "local",
      "command": "uvx",
      "args": ["--from", "git+https://github.com/navi00498/aem-troubleshooting-mcp-server", "aem-troubleshooting-mcp"],
      "env": { "AEM_URL": "http://localhost:4502", "AEM_USER": "admin", "AEM_PASSWORD": "admin" },
      "tools": ["*"]
    }
  }
}

Claude Desktop – claude_desktop_config.json:

{
  "mcpServers": {
    "aem": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/navi00498/aem-troubleshooting-mcp-server", "aem-troubleshooting-mcp"],
      "env": { "AEM_URL": "http://localhost:4502", "AEM_USER": "admin", "AEM_PASSWORD": "admin" }
    }
  }
}

Then ask things like:

• "Run a health check on my local AEM author and tell me what to fix first."

• "Is anything stuck in replication? What's at the head of the queue?"

• "error.log is full of traversal warnings – which queries, and which index would fix them?"

• "Show me the definition of cqPageLucene and whether it would cover a query on cq:template."

Compatibility

The request log appender is assumed to be /logs/request.log; pass log_name if yours differs.

Development

uv venv && source .venv/bin/activate
uv pip install -e . ruff
python -m unittest discover -s tests -v   # 34 tests: pure analysis, HTTP client vs mock, MCP protocol in-memory
ruff check . && ruff format --check .

CI runs lint, the test suite on Python 3.10–3.13 and an end-to-end stdio smoke test against the mock.

Project layout:

src/aem_mcp/
  server.py     # MCP tools + prompt (MCP Python SDK)
  client.py     # GET-only HTTP client, auth, error mapping
  analysis.py   # pure functions: summaries, warnings, guardrails (unit-tested)
  mock_aem.py   # fake AEM author used by tests, demo and CI

Roadmap

• Cloud Manager log download API for AEMaaCS

• Sling Content Distribution queue status

• Thread dump capture and analysis (blocked threads, long-running requests)

• Dispatcher cache/flush checks

• Package Manager and Sling job queue inspection

Disclaimer

Personal project, not affiliated with or endorsed by Adobe. Built from public AEM, Apache Sling, Apache Felix and Apache Jackrabbit Oak documentation. The mock server and sample logs are entirely synthetic.

License

MIT