Auditing a Drupal site usually means clicking through admin pages, exporting CSV files, and compiling spreadsheets. Content types here, field configurations there, module lists somewhere else. The information exists, but gathering it takes time.
Audit Export solves this by providing structured, programmatic access to your site's architecture. When combined with AI assistants through the Model Context Protocol (MCP), you can ask questions about your site and get answers pulled directly from the current configuration. No manual exports, no stale documentation.
What Audit Export Provides
Audit Export ships with reports covering content types, fields, views, modules, users, roles, taxonomies, and more. Each audit returns structured data you can export to CSV or consume programmatically.
The Audit Export Tool submodule takes this further by integrating with Drupal's Tool API module. This integration exposes every audit as a typed, discoverable tool that external systems can call. AI assistants can list available audits, run them on demand, and retrieve the results without you manually triggering exports.
If you create custom audit plugins for your site-specific needs, those automatically become available as tools too. This means AI assistants can access custom data that the default reports don't cover.
Installing Audit Export
Start by installing Audit Export on your site:
composer require drupal/audit_export
drush en audit_exportAudit Export can generally run on production environments, but you should test it in a local or development environment first. The audits read configuration and content data, then write report results to the database. Most sites handle this without issues, but site complexity varies. Audit Export accounts for large field counts and complex configurations, but it can't anticipate every custom setup. Test locally before deciding whether to run audits on production.
Enable the Audit Export Tool submodule to expose audit functionality through the Tool API:
drush en audit_export_toolThis submodule requires the Tool API module, which provides the typed tool interface that makes audits discoverable and callable:
composer require drupal/tool
drush en toolConnecting to AI Assistants with MCP
To let AI assistants access your audits, you need the Model Context Protocol (MCP) module. MCP bridges Drupal and AI tools by exposing Tool API plugins as MCP tools. Install it locally, not on production:
composer require drupal/mcp
drush en mcpThe MCP module creates an endpoint that AI clients connect to. You do not want this running on a live site where credentials could leak or where external tools might consume resources.
You can find the full installation and configuration guide in the official MCP documentation.
Setting Up an MCP User
Create a dedicated Drupal user for MCP connections. Go to People > Add user and create an account with a strong password.
Navigate to Configuration > Web Services > MCP (/admin/config/mcp) to enable authentication. You can choose between token-based authentication or basic authentication with username and password.
Create a new role for MCP access with these permissions:
- Use MCP server
- Access audits
- View published content (if you want the AI to read node data)
Assign the role to your MCP user. Do not grant administrative permissions or anything that allows content editing or configuration changes. The AI should read data, not modify it.
For complete configuration details, see the MCP setup documentation.
Connecting AI to Your Drupal Site
With Audit Export, Tool API, and MCP installed, you can connect AI tools to your site. The setup process varies depending on which tool you use.
Claude Desktop and Claude Code
For Claude Desktop and Claude Code, the recommended approach is using the Docker-based STDIO transport. This method is fully dockerized and handles the connection automatically.
The configuration uses a JSON file at:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%/Claude/claude_desktop_config.json
Add this configuration to the file:
{
"mcpServers": {
"mcp-server-drupal": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"DRUPAL_AUTH_USER",
"-e",
"DRUPAL_AUTH_PASSWORD",
"--network=host",
"ghcr.io/omedia/mcp-server-drupal:latest",
"--drupal-url=https://yoursite.ddev.site",
"--unsafe-net"
],
"env": {
"DRUPAL_AUTH_USER": "mcp_user",
"DRUPAL_AUTH_PASSWORD": "your_secure_password"
}
}
}
}
Replace yoursite.ddev.site with your local site URL and update the credentials with the MCP user you created. The --network=host flag allows the Docker container to access your local DDEV site. The --unsafe-net flag bypasses SSL verification for self-signed certificates during local development.
For Claude Code, you can also add the configuration via the command line:
claude mcp add --scope project mcp-server-drupal docker -e DRUPAL_AUTH_USER=mcp_user -e DRUPAL_AUTH_PASSWORD=your_password -- run -i --rm -e DRUPAL_AUTH_USER -e DRUPAL_AUTH_PASSWORD --network=host ghcr.io/omedia/mcp-server-drupal:latest --drupal-url=https://yoursite.ddev.site --unsafe-net
Restart Claude Desktop or Claude Code after saving the configuration. You should see the Drupal MCP server listed with the number of available tools.
Complete instructions for Claude integration are available in the MCP connection documentation.
ChatGPT with OpenAI Codex
For ChatGPT with OpenAI Codex, the recommended method is using the STDIO transport with the compiled binary. Download the appropriate binary for your platform from the GitHub releases page.
For macOS with Apple silicon, use the darwin-arm release (aarch64-apple-darwin). For other platforms, select the binary that matches your operating system and architecture.
Configure the binary in your Codex configuration file at ~/.codex/config.toml:
[mcp_servers.drupal]
command = "/path/to/mcp-server-drupal_darwin_arm"
args = ["--drupal-url", "https://yoursite.ddev.site"]
[mcp_servers.drupal.env]
DRUPAL_AUTH_USER = "mcp_user"
DRUPAL_AUTH_PASSWORD = "your_secure_password"
Replace /path/to/mcp-server-drupal_darwin_arm with the actual path where you saved the binary. Update the site URL and credentials to match your setup.
You can also use the HTTP transport method with Codex, though it may be slower. Full details are available in the STDIO transport documentation and OpenAI Codex MCP guide.
Debugging Connection Issues
If the AI tool does not list any MCP tools after configuration:
- Check that the MCP module is enabled:
drush pm:list | grep mcp - Verify your local site is accessible at the URL you provided
- Confirm the MCP user exists and has the correct role and permissions
- Check that authentication is enabled in the MCP configuration at
/admin/config/mcp - Verify your credentials are correct (wrong passwords are the most common issue)
- Look at your Drupal logs for authentication errors:
drush watchdog:show - For Docker connections, ensure
--network=hostis set if using DDEV
If tools appear but fail when called, the MCP user may lack permissions for the specific audit or endpoint being accessed. Review the role configuration.
Using Audit Export with AI
Once connected, AI assistants can discover which audits are available, run them on demand, and retrieve the results. You can ask questions about your site's architecture, and the AI will execute the appropriate audits to answer.
Initiating Audits
AI assistants can both read existing audit data and trigger new audits. When you ask a question, the AI determines which audits to run and executes them:
"What content types exist on this site?"
The AI runs the content type audit and returns the results.
"Run the module audit and show me which modules have available updates."
The AI executes the module audit and filters the results based on your question.
Because Audit Export exposes audits through the Tool API, the AI can discover available audits dynamically and call them as needed. You don't need to pre-export anything or keep CSV files updated.
Generating Comprehensive Site Documentation
One of the most practical uses is generating complete site audit documents. Ask the AI to run all available audits and compile them into a comprehensive markdown report:
"Run all available audits on this site and compile them into a comprehensive site audit document in markdown format."
The AI will execute each audit, format the results, and produce a structured markdown document covering content types, fields, views, modules, users, roles, taxonomies, and any custom audits you have installed. You can import this document directly into Google Docs, Microsoft Word, or any documentation system that supports markdown.
You can also request focused documentation:
"Create a content architecture document showing all content types, their fields, and relationships between them."
"Generate a module inventory report grouped by functionality, including version numbers and update status."
These documents serve as living documentation that stays current because the AI generates them directly from your site's actual configuration.
Custom Audits Become Available Automatically
If you create custom audit plugins for Audit Export, the Tool API integration automatically exposes them as callable tools. This happens without any additional configuration.
For example, if you build a custom audit that checks for broken links across all content, that audit becomes available to AI assistants the moment you enable it. You can then ask:
"Run the broken link audit and summarize which content types have the most broken links."
The AI discovers the custom audit through the Tool API, runs it, and analyzes the results.
This is particularly useful when you need site-specific reports that the default audits don't cover. Your custom business logic, custom entity types, or custom field configurations can all be audited and made available to AI assistants through the same mechanism.
Combining with Filesystem Access
The real power emerges when you combine Audit Export with filesystem access. Claude Code and OpenAI Codex have built-in filesystem capabilities. For Claude Desktop, you can enable filesystem access through the built-in filesystem extension or use third-party MCP servers like Filesystem Plus.
With both site audit data and codebase access, the AI can evaluate custom code in themes and modules. This is particularly useful when inheriting a site with custom development or planning refactoring work.
Custom Theme Analysis: Ask the AI to audit the content types and then review the custom theme for implementation details:
"Check what content types exist, then examine the custom theme and document which template files and preprocessing functions handle each content type."
"Identify all custom theme hooks in the theme and explain what they do in the context of the site's content architecture."
The AI correlates configured content types with their theme implementations, giving you a complete picture of how content gets rendered.
Custom Module Evaluation: Custom modules often contain business logic that's not visible in configuration. The AI can analyze custom module code in the context of site architecture:
"List all custom modules, then review their code to document what functionality each one provides and which Drupal APIs it uses."
"Find all custom field formatters and widgets in custom modules, then check which fields actually use them."
"Identify any custom entity types or plugins in custom modules and explain how they integrate with the rest of the site."
This helps you understand what custom code does and where it fits into the overall site architecture.
Code Quality and Modernization: The AI can audit both configuration and code to identify technical debt:
"Review the custom theme and modules for deprecated API usage and suggest modernization steps."
"Check if any custom code duplicates functionality that's now available in contrib modules."
"Identify custom preprocessing functions that might be replaceable with Twig filters or layout builder components."
These queries help scope refactoring work and identify opportunities to reduce custom code.
Migration and Upgrade Planning: When planning a platform upgrade or migration, understanding custom code dependencies is critical:
"Audit the custom modules and identify any that interact with contrib modules that don't have Drupal 10 versions yet."
"Review custom theme templates and identify which core templates they override, then check if those templates changed in newer Drupal versions."
The AI can flag compatibility concerns before you start the upgrade process.
Practical Examples
Site Overview: Ask the AI to summarize the site's architecture, including major content types, key modules, user roles, and active views. The AI runs multiple audits and synthesizes them into a high-level overview.
Migration Planning: Request an inventory of all content types with field counts, module compatibility status, and taxonomy usage. The AI compiles this into a structured report that serves as the foundation for migration planning.
Finding Configuration Drift: Ask the AI to identify content types with similar names or purposes but different field configurations, or modules that provide overlapping functionality. The AI can spot inconsistencies that might indicate technical debt.
Security Review: Request a report on all user roles, their permission counts, and which users are assigned to administrative roles. The AI provides a security-focused view of access control.
Use Cases
Agency Onboarding: When a new client site arrives, connect the AI and ask it to run comprehensive audits. It can list content types, installed modules, user roles, active views, and evaluate custom theme and module code. You get a complete technical overview, including what custom development exists and what it does, without manually clicking through admin pages or reading through code.
AI-Assisted Migrations: Planning a migration to a new platform or a Drupal version upgrade often starts with inventorying what exists. The AI can run audits on source and destination sites, compare the results, identify discrepancies, evaluate custom code for compatibility issues, and suggest what needs mapping or reconfiguration.
Developer Onboarding: New developers need to understand both the site's configuration and its custom code before they can contribute effectively. Instead of handing them documentation that may be outdated, let them ask the AI questions. The AI runs current audits and explains both what's configured and how custom code implements that configuration.