Joomla MCP (PHP)

Pure PHP Model Context Protocol server for administering Joomla 6.x through bounded, auditable semantic actions.

This is the community-facing PHP implementation. The TypeScript reference lives in joomengine/joomla-mcp-ts. Shared action catalogue, schemas, and security expectations live in joomengine/joomla-mcp-spec.

Design principles

• Native-first — Joomla models, ACL, events, and validation remain the authority.
• Bounded catalogue — only actions defined in joomla-mcp-spec are exposed.
• No passthrough — no generic HTTP, CLI, shell, PHP, SQL, or filesystem execution.
• Fail-closed — missing grants, unknown actions, and schema violations reject the request.
• Dependency injection — Laminas ServiceManager is the primary container.
• Shared contract — public MCP tools and write protocol match the TypeScript reference.

Stack

Concern	Choice	Notes
MCP protocol	mcp/sdk	Official PHP SDK (framework-agnostic)
DI container	laminas/laminas-servicemanager	Preferred Laminas component
HTTP client	joomla/http	Joomla Framework alignment
JSON Schema	opis/json-schema	Validate inputs against shared schemas
Tests	PHPUnit 11	Unit + contract tests

Laravel is not used. Symfony application components are not used; the official MCP SDK is the only protocol dependency and is deliberately framework-agnostic.

Requirements

• PHP 8.3 or newer
• Composer 2
• A Joomla 6.1+ site with Web Services enabled
• Optionally the companion plugin from the TypeScript repository for native local actions

Status

Foundation bootstrap. Discovery tools and catalog loading are in place. Full write protocol, permission grants, and the complete action surface are built against joomla-mcp-spec as families are extracted there.

Quick start (stdio)

composer install
cp config/sites.example.json config/sites.json
# Set JOOMLA_MCP_TOKEN (and optional approval secret) in the environment
php bin/joomla-mcp

Example MCP client entry:

{
  "mcpServers": {
    "joomla": {
      "command": "php",
      "args": ["/path/to/joomla-mcp/bin/joomla-mcp"],
      "env": {
        "JOOMLA_MCP_CONFIG": "/path/to/joomla-mcp/config/sites.json",
        "JOOMLA_MCP_TOKEN": "your-joomla-api-token"
      }
    }
  }
}

Sister projects

Repository	Role
joomla-mcp-ts	TypeScript / Node reference
joomla-mcp-spec	Shared catalogue and contracts
this repository	Pure PHP implementation

License

GNU General Public License, version 2 or later (GPL-2.0-or-later).