MCP Server for Joomla

A Joomla 4, 5 and 6 component that exposes a Model Context Protocol (MCP) server over HTTP JSON-RPC. It lets MCP clients such as Claude Desktop and Cursor work with Joomla content through the site's own Joomla Web Services API.

Version: 1.7.0 · Requires: Joomla 4, 5 or 6 · PHP 8.1+ · Licence: GPL-2.0-or-later

Features

• Administrator dashboard with request summary (totals, error rate and auth failures), a requests-per-day chart, top tools and methods, and a requests log
• One-click Claude Desktop extension (.mcpb), generated on demand from the administrator or attached to every release
• Security with bearer token authentication, optional IP allow-listing and CORS origin control
• Configurable fixed-window rate limiting
• Response caching through Joomla's cache layer
• JSON Schema validation for MCP tool inputs
• Health endpoint for monitoring
• MCP Resources (recent published articles as joomla://article/{id}) and guided Prompts (draft, SEO audit, translate)
• Joomla update server metadata for official releases

MCP Tools

The component exposes 71 tools grouped by Joomla domain. List tools include a pagination object (total_count, count, offset, has_more, next_offset) so agents can page through large result sets. Write tools use Joomla's Web Services API where possible; a small number of behaviours not exposed cleanly through Web Services (custom module HTML writes, multilingual associations, template file editing) are handled through Joomla's database or filesystem APIs.

Articles

Categories

Tags

Article versions

Article versioning tools require Joomla article versioning to be enabled.

Custom modules

Modules

Menus and menu items

Media

Content languages

Installed languages

Template styles

Installed templates

Template files

Extensions

install_extension, uninstall_extension and update_template_file are disabled by default because they allow code execution on the server. Remove them from the Disabled Tools list in the component options to opt in.

Multilingual associations

Maintenance

Site diagnostics

get_rendered_page fetches the public site as an anonymous visitor so the result matches what a guest actually sees after the template and content plugins run. check_internal_links never issues HTTP requests for external URLs. seo_audit_articles does not inspect metakey — Joomla stopped using keyword meta tags in 2009.

Not covered (by design)

User management, Joomla global configuration, custom fields (com_fields), contacts, banners and redirects are deliberately not exposed as tools. User accounts and global configuration in particular would widen the blast radius of a leaked bearer token well beyond content management. If your workflow needs one of these domains, open an issue — they are candidates for opt-in tools in a future release.

MCP Resources

When Enable Resources is on (the default), MCP clients can attach published articles as context without a tool call.

• resources/list returns up to 50 recent published articles, newest first, as joomla://article/{id}.
• resources/templates/list advertises the template joomla://article/{id}.
• resources/read returns the article HTML (introtext + fulltext, mimeType text/html).

Turning the option off omits the resources capability, returns empty lists, and answers resources/read with method-not-found.

MCP Prompts

When Enable Prompts is on (the default), MCP clients can pick guided workflows from a menu:

Turning the option off omits the prompts capability, returns an empty list, and answers prompts/get with method-not-found.

Installation

Download the latest com_mcpserver-<version>.zip package from the GitHub releases page, then install it in Joomla Administrator via System → Install → Extensions.

For a local development build:

./build.sh

The build creates com_mcpserver-<version>.zip at the repository root. The version is read from mcpserver.xml.

Configuration

Open Administrator → Components → MCP Server → Options.

Key settings:

• Server Name: identifier returned in MCP server information.
• Base URL: base URL of the Joomla site. Leave empty to use the current site.
• API Token: Joomla Web Services API token used for outbound REST calls.
• Verify SSL: verifies SSL certificates for outbound requests.
• Resolve Host To IP: optional. Pins the Base URL hostname to a specific IP (e.g. 127.0.0.1) for the component's outbound REST calls only. Use when the server cannot reach its own public hostname (NAT hairpinning); the Host header and TLS validation still use the real hostname, so Verify SSL can stay on.
• Cache TTL: response cache lifetime in seconds.
• Require Auth: requires MCP clients to send a bearer token.
• MCP Bearer Token: token clients must send in Authorization: Bearer.
• IP Allow List: comma-separated client IP allow list.
• Allowed Origins: comma-separated CORS origin allow list.
• Trusted Proxies: comma-separated proxy IPs trusted for X-Forwarded-For.
• Read-Only Mode: when enabled, only read-only tools may run; every tool that writes, deletes or installs anything is blocked.
• Disabled Tools: comma- or newline-separated MCP tool names to block (e.g. delete_article). Defaults to the code-execution tools (install_extension, uninstall_extension, update_template_file); remove them to opt in, or enter none to allow all tools (an emptied field reverts to the defaults when saved).
• Enable Resources: when enabled (the default), MCP clients can list and read recent published articles as joomla://article/{id} resources.
• Enable Prompts: when enabled (the default), MCP clients can use the draft, SEO audit and translate article prompts.
• Rate Limit Requests and Rate Limit Window: fixed-window rate limit settings.

Configuring the API Token

The API Token setting holds a Joomla Web Services API token. The component uses it to make outbound REST calls to your site's own Joomla Web Services API, which is how most MCP tools read and write content. Without a valid token, those tools will fail.

1. Enable the Web Services API. In the Joomla administrator, go to System → Global Configuration → Server and ensure the Web Services components are available. The relevant plugins live under System → Plugins; enable Web Services - Content (and any other Web Services - plugins for the data you want to access). The API plugin System - Joomla API Authentication must also be enabled — it is by default.

2. Create a token for a user. Tokens are tied to a Joomla user account, and API calls run with that user's permissions, so use an account that has the access the MCP tools need (for full functionality, a Super User or an account with the equivalent component permissions).

   • Go to Users → Manage, edit the chosen user, and open the Joomla API Token tab.
   • Set Token Enabled to Yes, click Save, then copy the generated token. (If the tab is missing, enable the User - Joomla API Token plugin under System → Plugins.)

3. Paste the token into the component options. Back in Components → MCP Server → Options, paste the value into API Token and click Save.

4. Verify the API is reachable. The component calls your site's own API under /api/, so the web server must route that path to Joomla's API application. On Apache this works out of the box — Joomla's core .htaccess rewrites /api/ requests to api/index.php. On nginx there is no equivalent by default, so every tool fails while health.ping still reports ok (that endpoint only checks the component itself, not the outbound API layer). Check with:

   curl -i "https://example.com/api/index.php/v1/content/articles?page[limit]=1" \
     -H "X-Joomla-Token: <API_TOKEN>" -H "Accept: application/vnd.api+json"
   

   The status code alone is not enough — the response format tells you where the problem lies:

   Response from /api/…	Actual cause
   HTML page	The request never reached the API application → web server routing (see the nginx note below)
   JSON 404	The relevant Web Services - * plugin is disabled
   JSON 401/403	The API token is invalid, or its user lacks sufficient permissions

   On nginx, add this block before the general location / block, then run nginx -t and reload:

   location /api {
       try_files $uri $uri/ /api/index.php$is_args$args;
   }
   

Security note: treat the API token like a password. It grants the token user's level of access to your site. Store it only in trusted configuration, and regenerate it (by toggling Token Enabled off and on) if it may have been exposed.

Endpoints

Claude Desktop Extension (.mcpb)

For Claude Desktop the easiest client setup is the bundled extension: a .mcpb file (a zip in the MCPB format) that installs with a double-click. It contains the component's own zero-dependency HTTP bridge, so there is no Node.js install, no npm package and no hand-edited JSON — Claude Desktop supplies the Node runtime itself, and the connector appears as MCP Server for Joomla with the project logo.

Download it from your own site (recommended). In Administrator → Components → MCP Server, click Download Claude Desktop extension in the MCP Client Configuration card. The component generates a personalised bundle on the fly: the endpoint URL is pre-filled and the connector is named after the site, which keeps several Joomla sites clearly distinguishable in Claude Desktop.

Or download the generic bundle. Every GitHub release also publishes com_mcpserver.mcpb alongside the component zip.

To install:

1. Double-click the downloaded .mcpb file (requires Claude Desktop).
2. Enter the MCP endpoint URL — pre-filled when the bundle was downloaded from your site; otherwise copy the RPC Endpoint shown under Components → MCP Server.
3. Enter the MCP Bearer Token from Components → MCP Server → Options.

The bearer token is never embedded in the downloaded file: it remains a one-time paste into Claude Desktop's settings, so no live credential lands in your downloads folder, backups or sync folders.

Desktop Client Bridge

Claude Desktop users: prefer the .mcpb extension above — it needs no Node.js or manual configuration. The bridge below remains for other stdio clients and custom setups.

For MCP clients that use stdio transport, run the included Node.js bridge. After installation it is located at components/com_mcpserver/mcp-http-bridge.js in your Joomla site root. When working from a repository checkout or extracted release zip, use site/mcp-http-bridge.js instead.

node components/com_mcpserver/mcp-http-bridge.js <endpoint-url> [bearer-token]

Example:

node components/com_mcpserver/mcp-http-bridge.js "https://example.com/index.php?option=com_mcpserver&task=rpc.handle" "$MCP_BEARER_TOKEN"

MCP client configuration

For your agent (e.g. Codex, Cursor, Claude, Hermes, OpenClaw), point your MCP client configuration file at the bundled bridge:

{
  "mcpServers": {
    "joomla": {
      "command": "node",
      "args": [
        "/path/to/joomla/components/com_mcpserver/mcp-http-bridge.js",
        "https://example.com/index.php?option=com_mcpserver&task=rpc.handle"
      ],
      "env": {
        "HTTP_AUTH_BEARER": "your-mcp-bearer-token"
      }
    }
  }
}

The bridge speaks plain HTTP POST with no SSE or transport negotiation, so connection failures surface their real cause.

Windows / Claude Desktop

Claude Desktop on Windows spawns MCP servers with a truncated PATH that excludes the Node.js directory, so "command": "npx" (or a bare "node") fails with spawn npx ENOENT. Any cmd.exe layer — npx, npx.cmd or cmd /c — must also be avoided: cmd.exe treats & as a command separator and splits the endpoint URL at &task=, which the site answers with an HTML 404. Use the absolute path to node.exe and invoke the bridge directly. Copy mcp-http-bridge.js to the Windows machine first (from components/com_mcpserver/ in the Joomla site root, or from the release zip):

{
  "mcpServers": {
    "joomla": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": [
        "C:\\path\\to\\mcp-http-bridge.js",
        "https://example.com/index.php?option=com_mcpserver&task=rpc.handle"
      ],
      "env": {
        "HTTP_AUTH_BEARER": "your-mcp-bearer-token"
      }
    }
  }
}

Fully quit Claude Desktop from the tray after editing the configuration — closing the window is not enough.

The bearer token can also be supplied through HTTP_AUTH_BEARER. Set MCP_IGNORE_SSL=1 only for local development with self-signed certificates.

Release Build

composer validate --working-dir=admin --no-check-publish
./build.sh

Licence

MCP Server for Joomla is free software released under GPL-2.0-or-later.