Overview

The Drupal MCP Server using STDIO transport is a PHP-based adapter that exposes a Drupal site’s capabilities to tools and language-model agents using the Model Context Protocol (MCP). Instead of operating over HTTP, this server communicates over standard input and output (STDIO), making it easy to run as a subprocess for command-line workflows, editor integrations, or orchestration from other programs.

Using STDIO as the transport keeps integration simple and secure: the server runs on the same host as the Drupal codebase, has local access to the site, and exchanges structured JSON messages on stdin/stdout with an supervising process (for example, an LLM agent runner or a CLI orchestrator). This pattern is ideal for automating site maintenance, content operations, code generation, and interactive developer tooling without exposing site APIs externally.

Features

Lightweight MCP implementation tailored for Drupal sites
STDIO transport for running as a subprocess (no network port required)
Access to typical Drupal resources: entities, files, configuration, and cache
Ability to run site-local commands and scripts (Drush, PHP bootstrap)
Designed for integration with LLM agents, CLI tools, and editor extensions
Environment-driven configuration so the server runs in diverse environments (CI, dev machines, containers)

Installation / Configuration

Clone the repository and install dependencies (example using Composer):

git clone https://github.com/Omedia/mcp-server-drupal.git
cd mcp-server-drupal
composer install

Configure environment variables (example .env file):

# Path to your Drupal root (directory containing index.php)
DRUPAL_ROOT=/var/www/html

# Base URI of your site (used for generating absolute URLs)
SITE_URI=http://localhost:8888

# Logging level: debug, info, warn, error
LOG_LEVEL=info

Start the server as a subprocess. The exact entrypoint may differ per release; the pattern below demonstrates running a PHP CLI script that communicates over STDIO:

# Example: run the server in foreground (stdout/stderr will show logs)
php bin/mcp-server-drupal.php

Supervising process (agent/CLI) should spawn the server as a child process and communicate by writing JSON messages to stdin and reading responses from stdout. See the Node.js example below.

Node.js example: spawn the MCP server and exchange messages over STDIO

const { spawn } = require('child_process');

const proc = spawn('php', ['bin/mcp-server-drupal.php'], { stdio: ['pipe', 'pipe', 'inherit'] });

// Example: send a JSON "initialize" message (MCP framing depends on client)
const msg = JSON.stringify({ type: 'initialize', body: { site: 'my-site' } }) + '\n';
proc.stdin.write(msg);

// Read responses from stdout
proc.stdout.on('data', data => {
  const text = data.toString();
  console.log('Server response:', text);
});

Note: The precise MCP message schema and framing should match your MCP client implementation.

Available Resources

The server exposes a set of tools/resources representing common Drupal capabilities. Typical resources an MCP server for Drupal can provide include:

Entities (node, taxonomy, user): read/list/create/update/delete operations
Files: upload, fetch, and serve metadata
Configuration: read and export site configuration key-values
Database/querying: run read-only queries or controlled migrations
Drush/CLI: execute site-local maintenance commands in a controlled way
Codebase/file access: read and optionally modify module/theme files (careful with write operations)
Search/index: query the active search index (if available)

Each resource is represented as a callable tool in the MCP model so the supervising agent can request actions and receive structured results.

Use Cases

Automated content updates: run the server in a CI job or agent process to programmatically create or update nodes, apply taxonomy changes, or import CSV content into the site.
- Example: spawn the server, send a request to the “entity:create” tool for node type “article” with body and metadata, then confirm via “entity:load”.
Local code-assisted authoring: integrate with an LLM-based assistant inside an editor to scaffold modules, generate hook implementations, or propose configuration changes. The assistant runs the MCP server locally to inspect the actual site and produce contextual code suggestions.
Migration and data transformation: orchestrate multi-step imports where the agent uses the server to run controlled database reads, map results to entities, and create content via the entity APIs.
Maintenance scripts and audits: perform security checks, configuration drift detection, or run Drush commands through the MCP toolset, all from a supervising process that logs and controls operations.
Developer CLI tools: wrap the MCP server in a CLI that exposes high-level administrative commands that are executed with full context of the site without opening network endpoints.

Security and Best Practices

Run the MCP STDIO server only in trusted environments; STDIO implies local access but the server has full access to the Drupal codebase and database.
Minimize write capabilities where not needed. For tasks that only need read access (audit, discovery), restrict write tools.
Integrate robust logging and operation approval workflows when an agent can perform destructive actions.
Use containerization or dedicated CI runners to isolate runs that perform changes.

Troubleshooting

If the supervising client does not receive responses, ensure the server process is running and that stdin/stdout are correctly attached by the supervisor.
Check logs (stderr or server log files) for bootstrap errors—common issues include incorrect DRUPAL_ROOT or missing Composer dependencies.
For protocol mismatches, validate the message framing and JSON schema expected by your MCP client; adjust client/server framing if messages are buffered.

This server pattern streamlines building local developer tooling and LLM integrations for Drupal by providing a predictable STDIO-based MCP transport and a set of Drupal-aware tools that can be orchestrated from scripts, editors, or agent processes.

Drupal MCP Server Using STDIO Transport