mcp-mokosuite-api/docs/INSTALLATION.md

Installation

Prerequisites

• Node.js 20.0.0 or later
• npm (included with Node.js)
• A Joomla 4/5/6 site with the Web Services API enabled
• A Joomla API token (generated in Users > Edit User > API Token tab)

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:

1. Connection name — a label for this site (e.g. production, staging)
2. Joomla site URL — the base URL of the site (e.g. https://www.example.com)
3. API token — the Joomla API token for authentication
4. TLS verification — whether to skip certificate verification (for self-signed certs)

Run npm run setup again to add more connections.

Register with Claude Code

Add to your global Claude Code config (~/.claude.json):

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

Or add to a project-level .mcp.json:

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

Restart Claude Code after adding the server.

Generating a Joomla API Token

1. Log in to the Joomla admin panel
2. Go to Users > Manage > select your user
3. Click the API Token tab
4. Click Save to generate a token
5. Copy the token value — it will not be shown again

The token must belong to a user with sufficient permissions for the operations you want to perform (e.g. Super Users for full access).

Configuration File

The config is stored at ~/.joomla-api-mcp.json:

{
  "defaultConnection": "production",
  "connections": {
    "production": {
      "baseUrl": "https://www.example.com",
      "apiToken": "your-api-token"
    },
    "staging": {
      "baseUrl": "https://staging.example.com",
      "apiToken": "your-staging-token",
      "insecure": true
    }
  }
}

Field	Required	Description
defaultConnection	Yes	Name of the default connection
connections	Yes	Map of named connections
baseUrl	Yes	Joomla site URL (no trailing slash)
apiToken	Yes	Joomla API token (Bearer auth)
insecure	No	Set true to skip TLS verification

Verification

After setup, verify the server starts correctly:

npm start

If configured correctly, the server will start listening on stdio. If the config is missing or invalid, it will print an error with instructions.

Troubleshooting

"Failed to load config" error

The config file ~/.joomla-api-mcp.json is missing or malformed. Run npm run setup to create it.

"terminated" or connection errors

• Verify the Joomla site is reachable from your machine
• For self-signed certs, set "insecure": true in the connection config
• Ensure the API token is valid and not expired

"Resource not found" on certain endpoints

Some Joomla API endpoints require specific components to be installed and enabled. For example, the menus API requires com_menus to expose its Web Services routes.

Revision History

Date	Version	Author	Notes
2026-04-23	0.0.1	jmiller	Initial installation guide