MokoConsulting/mcp-mokowaas-api
1
0
Fork 0
Code Issues 1 Pull Requests Releases 2 Wiki Activity

chore: cascade main → dev (5c16823) [skip ci] #4

Merged
jmiller merged 1 commits from main into dev 2026-05-10 18:41:58 +00:00
Conversation 0 Commits 1 Files Changed 1
+65 -257
1 changed files with 65 additions and 257 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+65 -257
View File
@@ -1,296 +1,104 @@
<!-- Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
This file is part of a Moko Consulting project.
SPDX-LICENSE-IDENTIFIER: GPL-3.0-or-later
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the IMPLIED WARRANTY of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License (./LICENSE).
# FILE INFORMATION
DEFGROUP: joomla-api-mcp.Documentation
INGROUP: joomla-api-mcp
REPO: https://git.mokoconsulting.tech/MokoConsulting/joomla-api-mcp
VERSION: 01.00.00
PATH: ./README.md
BRIEF: MCP server for Joomla Web Services API operations
-->
[![Version](https://img.shields.io/badge/version-01.00.00-blue.svg?logo=v&logoColor=white)](https://git.mokoconsulting.tech/MokoConsulting/joomla-api-mcp/releases/tag/v00)
[![License](https://img.shields.io/badge/license-GPL--3.0--or--later-green.svg?logo=gnu&logoColor=white)](LICENSE)
[![Node](https://img.shields.io/badge/Node.js-20%2B-339933.svg?logo=node.js&logoColor=white)](https://nodejs.org)
# joomla-api-mcp
[![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)
MCP server for Joomla Web Services API operations
A Model Context Protocol (MCP) server that exposes the Joomla 4/5/6 Web Services API as tools for AI assistants.
![Language](https://img.shields.io/badge/Markdown-000000?style=flat-square&logo=markdown&logoColor=white) ![License](https://img.shields.io/badge/license-GPL--3.0--or--later-green?style=flat-square) ![Wiki](https://img.shields.io/badge/wiki-joomla-api-mcp-blue?style=flat-square)
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
Model Context Protocol server for the Joomla Web Services API -- full CRUD for articles, categories, users, menus, contacts, tags, media, plugins, and more.
- [Background](#background)
- [Install](#install)
- [Usage](#usage)
- [Tools](#tools)
- [Configuration](#configuration)
- [Contributing](#contributing)
- [License](#license)
- [Maintainers](#maintainers)
---
## Background
| | |
|---|---|
| **Type** | MCP Server |
| **Language** | Node.js |
| **Tools** | 67 tools across 15 resource groups |
| **License** | GPL-3.0-or-later |
| **Platform** | [Gitea](https://git.mokoconsulting.tech/MokoConsulting/joomla-api-mcp) (primary) |
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
## Overview
Supports multiple named connections for managing several Joomla instances from a single MCP server.
joomla-api-mcp wraps the entire Joomla Web Services REST API into MCP tools that Claude Code can call directly. It supports multi-site connections via named connection configs.
## Install
### Resource Coverage
```sh
git clone https://git.mokoconsulting.tech/MokoConsulting/joomla-api-mcp.git
cd joomla-api-mcp
npm install
npm run build
npm run setup
```
| Group | Operations |
|-------|------------|
| Articles | list, get, create, update, delete |
| Categories | list, create, update, delete |
| Users | list, get, create, update, delete, groups |
| Contacts | list, get, create, update, delete |
| Menus | list types, list/get/create/update/delete items |
| Tags | list, get, create, update, delete |
| Custom Fields | list, get, create, delete |
| Plugins | list, update (enable/disable) |
| Modules | list |
| Templates | list |
| Media | list, get file, delete file, create folder |
| Banners | list, get, create, delete, list clients |
| Newsfeeds | list, get, create, delete |
| Messages | list, get, send, delete |
| Redirects | list, create, delete |
| Config | get, update |
| Content History | list versions |
| Checkin | unlock checked-out items |
| Associations | list multilingual associations |
| Generic | raw API request, list connections |
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
## Wiki Pages
### Add to Claude Code
### Guides
In your Claude Code MCP settings (`~/.claude.json` or project `.mcp.json`):
- [Installation](https://git.mokoconsulting.tech/MokoConsulting/joomla-api-mcp/wiki/INSTALLATION) -- setup, .env configuration, Claude Code registration, multi-site connections
```json
{
"mcpServers": {
"joomla": {
"command": "node",
"args": ["/path/to/joomla-api-mcp/dist/index.js"]
}
}
}
```
### Reference
### Configuration
- [API](https://git.mokoconsulting.tech/MokoConsulting/joomla-api-mcp/wiki/API) -- all 67 tools with parameters, grouped by resource type
- [Architecture](https://git.mokoconsulting.tech/MokoConsulting/joomla-api-mcp/wiki/ARCHITECTURE) -- source file map, component design, connection handling
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.
### Templates
You can also create the config manually. Copy `config.example.json` to `~/.joomla-api-mcp.json` and edit:
- [Templates Index](https://git.mokoconsulting.tech/MokoConsulting/joomla-api-mcp/wiki/templates-index) -- workflow and config templates
- [README Template](templates-README-template) -- README template for MCP repos
```sh
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):
## Related Wikis
```json
{
"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"
}
}
}
```
| Repo | Purpose |
|------|---------|
| [backup-mcp](https://git.mokoconsulting.tech/MokoConsulting/backup-mcp/wiki) | Backup MCP (uses Joomla API for Akeeba) |
| [MokoWaaS](https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS/wiki) | Joomla WaaS system plugin |
| [Template-Client-WaaS](https://git.mokoconsulting.tech/MokoConsulting/Template-Client-WaaS/wiki) | Client site template |
| [MokoOnyx](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx/wiki) | Joomla admin template |
| 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 (67)
> **[MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki)** -- central standards hub for all Moko Consulting projects.
### 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
## Documentation
| 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 |
### Contacts
| Tool | Description |
|------|-------------|
| `joomla_contacts_list` | List contacts with optional search |
| `joomla_contact_get` | Get a single contact by ID |
| `joomla_contact_create` | Create a new contact |
| `joomla_contact_update` | Update an existing contact |
| `joomla_contact_delete` | Delete a contact |
### 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 |
| `joomla_menu_item_create` | Create a new menu item |
| `joomla_menu_item_update` | Update a menu item |
| `joomla_menu_item_delete` | Delete a menu item |
### Tags
| Tool | Description |
|------|-------------|
| `joomla_tags_list` | List tags with optional search |
| `joomla_tag_get` | Get a single tag by ID |
| `joomla_tag_create` | Create a tag |
| `joomla_tag_update` | Update a tag |
| `joomla_tag_delete` | Delete a tag |
### Custom Fields
| Tool | Description |
|------|-------------|
| `joomla_fields_list` | List custom fields for a context |
| `joomla_field_get` | Get a single custom field by ID |
| `joomla_field_create` | Create a custom field |
| `joomla_field_delete` | Delete a custom field |
### Banners
| Tool | Description |
|------|-------------|
| `joomla_banners_list` | List banners |
| `joomla_banner_get` | Get a single banner by ID |
| `joomla_banner_create` | Create a new banner |
| `joomla_banner_delete` | Delete a banner |
| `joomla_banner_clients_list` | List banner clients |
### Newsfeeds
| Tool | Description |
|------|-------------|
| `joomla_newsfeeds_list` | List newsfeeds |
| `joomla_newsfeed_get` | Get a single newsfeed by ID |
| `joomla_newsfeed_create` | Create a new newsfeed |
| `joomla_newsfeed_delete` | Delete a newsfeed |
### Messages
| Tool | Description |
|------|-------------|
| `joomla_messages_list` | List private messages |
| `joomla_message_get` | Get a single private message |
| `joomla_message_send` | Send a private message to a user |
| `joomla_message_delete` | Delete a private message |
### Media
| Tool | Description |
|------|-------------|
| `joomla_media_list` | List media files in a folder |
| `joomla_media_file_get` | Get metadata for a specific media file |
| `joomla_media_file_delete` | Delete a media file |
| `joomla_media_folder_create` | Create a new media folder |
### Redirects
| Tool | Description |
|------|-------------|
| `joomla_redirects_list` | List URL redirects |
| `joomla_redirect_create` | Create a URL redirect |
| `joomla_redirect_delete` | Delete a URL redirect |
### 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_content_history_list` | List version history for a content item |
| `joomla_checkin` | Check in (unlock) a checked-out content item |
| `joomla_associations_list` | List multilingual associations for a content item |
| `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.
Full documentation is available on the [Wiki](https://git.mokoconsulting.tech/MokoConsulting/joomla-api-mcp/wiki).
## Contributing
Contributions are welcome! Please read [CONTRIBUTING.md](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.md) Code of Conduct.
See the wiki for development guidelines and contribution instructions.
## License
This project is licensed under the GNU General Public License v3.0 or later - see the [LICENSE](LICENSE) file for details.
This project is licensed under the GNU General Public License v3.0 or later -- see the [LICENSE](LICENSE) file.
Copyright © 2026 Moko Consulting <hello@mokoconsulting.tech>
---
## Maintainers
[@mokoconsulting-tech](https://git.mokoconsulting.tech/MokoConsulting)
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 |
*[Moko Consulting](https://mokoconsulting.tech) -- [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)*