joomla-api-mcp

A Model Context Protocol (MCP) server that exposes the Joomla 4/5/6 Web Services API as tools for AI assistants.

Connects to Joomla instances over HTTP using the built-in REST API (/api/index.php/v1) and API token authentication. Claude, Cursor, and other MCP clients can manage articles, categories, users, menus, plugins, and more — without SSH or direct server access.

Table of Contents

• Background
• Install
• Usage
• Tools
• Configuration
• Contributing
• License
• Maintainers

Background

Joomla 4+ ships with a full Web Services API that supports content management, user administration, and site configuration over REST. This MCP server wraps that API into structured tools, enabling:

• Article management (list, create, update, delete, publish)
• Category management (list, create, update, delete)
• User administration (list, create, update, delete, groups)
• Menu and menu item inspection
• Plugin listing and enable/disable toggling
• Module and template listing
• Tag, contact, banner, and newsfeed management
• Media file browsing
• Application configuration read/write
• Private messaging
• Custom field inspection
• Raw API passthrough for any endpoint

Supports multiple named connections for managing several Joomla instances from a single MCP server.

Install

git clone https://git.mokoconsulting.tech/MokoConsulting/joomla-api-mcp.git
cd joomla-api-mcp
npm install
npm run build
npm run setup

The setup wizard will prompt for your Joomla site URL and API token. Run it again to add more connections — each site gets its own name, URL, and API key so you can manage multiple Joomla instances from a single MCP server.

Usage

Add to Claude Code

In your Claude Code MCP settings (~/.claude.json or project .mcp.json):

{
  "mcpServers": {
    "joomla": {
      "command": "node",
      "args": ["/path/to/joomla-api-mcp/dist/index.js"]
    }
  }
}

Configuration

The easiest way to configure is npm run setup, which walks you through it interactively. Run it multiple times to add connections for each Joomla site you manage.

You can also create the config manually. Copy config.example.json to ~/.joomla-api-mcp.json and edit:

cp config.example.json ~/.joomla-api-mcp.json

Each connection needs the Joomla site's base URL and an API token (generated in Joomla under Users > Edit User > API Token):

{
  "defaultConnection": "production",
  "connections": {
    "local-dev": {
      "baseUrl": "https://localhost:8080",
      "apiToken": "your-joomla-api-token-here",
      "insecure": true
    },
    "production": {
      "baseUrl": "https://www.example.com",
      "apiToken": "your-production-api-token"
    },
    "staging": {
      "baseUrl": "https://staging.example.com",
      "apiToken": "your-staging-api-token"
    }
  }
}

Field	Required	Description
baseUrl	Yes	Joomla site URL (no trailing slash)
apiToken	Yes	Joomla API token (Bearer auth)
insecure	No	Skip TLS verification for self-signed certs

Tools

Articles

Tool	Description
joomla_articles_list	List articles with optional category, state, and search filters
joomla_article_get	Get a single article by ID
joomla_article_create	Create a new article
joomla_article_update	Update an existing article
joomla_article_delete	Delete an article

Categories

Tool	Description
joomla_categories_list	List content categories
joomla_category_create	Create a new category
joomla_category_update	Update a category
joomla_category_delete	Delete a category

Users

Tool	Description
joomla_users_list	List users with optional search, group, and state filters
joomla_user_get	Get a single user by ID
joomla_user_create	Create a user with auto-generated secure password
joomla_user_update	Update a user
joomla_user_delete	Delete a user
joomla_user_groups_list	List user groups

Menus

Tool	Description
joomla_menus_list	List menu types
joomla_menu_items_list	List menu items for a menu type
joomla_menu_item_get	Get a single menu item by ID

Plugins

Tool	Description
joomla_plugins_list	List plugins with optional type, state, and search filters
joomla_plugin_update	Enable or disable a plugin

Other

Tool	Description
joomla_modules_list	List site or admin modules
joomla_templates_list	List site or admin templates
joomla_languages_list	List installed content languages
joomla_tags_list	List tags
joomla_tag_create	Create a tag
joomla_fields_list	List custom fields for a context
joomla_contacts_list	List contacts
joomla_banners_list	List banners
joomla_newsfeeds_list	List newsfeeds
joomla_messages_list	List private messages
joomla_message_get	Get a single private message
joomla_media_list	List media files in a folder
joomla_config_get	Get application configuration
joomla_config_update	Update application configuration values
joomla_api_request	Raw API request to any Joomla endpoint
joomla_list_connections	List configured connections

All tools accept an optional connection parameter to target a specific named connection.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

This project follows the Contributor Covenant Code of Conduct.

License

This project is licensed under the GNU General Public License v3.0 or later - see the LICENSE file for details.

Copyright © 2026 Moko Consulting hello@mokoconsulting.tech

Maintainers

@mokoconsulting-tech

For questions or support, please contact: hello@mokoconsulting.tech

Revision History

Date	Version	Author	Notes
2026-04-23	0.0.1	jmiller	Initial MCP server with Joomla Web Services API tools