Joomla MCP Server

Crear artículos en un sitio web de Joomla usando su API.

Documentación

Servidor MCP de Joomla

Conecta un asistente de IA a tu sitio web existente de Joomla 4 o 5 para que pueda leer y gestionar artículos, categorías, etiquetas y otro contenido compatible del sitio.

Debes configurar dos lugares: tu sitio web de Joomla y el ordenador que ejecuta tu asistente de IA. Este servidor Python se ejecuta en tu ordenador y llama a la API integrada de Servicios Web de Joomla a través de HTTPS. No instalas este repositorio como una extensión de Joomla ni lo subes a tu proveedor de alojamiento web. Tu aplicación de IA debe ser compatible con servidores MCP locales mediante stdio; el ejemplo siguiente utiliza Claude Desktop.

Configura tu sitio web de Joomla

1. Activa los plugins necesarios

Inicia sesión en el Administrador de Joomla como Super Usuario. Abre Sistema → Gestionar → Plugins (o Sistema → Plugins, según el diseño de tu administrador). Busca y activa:

Plugin	Necesario para
Autenticación API - Token de Servicios Web de Joomla	Autenticar solicitudes de API con tu token
Usuario - Token de API de Joomla	Crear y gestionar el token de API de un usuario
Servicios Web - Contenido	Artículos, categorías de contenido y campos de artículo

Empieza con estos tres. Si quieres herramientas adicionales, activa también el plugin correspondiente Servicios Web - Etiquetas, Medios, Menús, Módulos o Usuarios. Las herramientas de medios requieren Joomla 4.1 o posterior. Los campos personalizados también necesitan el componente Campos de Joomla y los plugins de campos.

2. Elige la cuenta de Joomla que usará el asistente

El token de API pertenece a un usuario de Joomla. Las solicitudes tienen los permisos de ese usuario. Usa una cuenta dedicada para esta conexión, en lugar de tu cuenta habitual de Super Usuario.

Para una cuenta dedicada:

Abre Usuarios → Grupos → Nuevo y crea un grupo como MCP Content Editors. Para un punto de partida restringido, selecciona Registrado como grupo principal.
Abre Sistema → Configuración Global → Permisos, selecciona tu grupo y permite Inicio de sesión en Servicios Web (core.login.api). También permite Inicio de sesión de Administrador para que esta cuenta pueda abrir su propio perfil y copiar su token. Comprueba que los permisos calculados muestren Permitido; deja sin configurar el acceso de Super Usuario.
Para la gestión de artículos, abre Contenido → Artículos → Opciones → Permisos. Da al grupo Acceso a la Interfaz de Administración para el componente Artículos, y luego solo las acciones que necesite: Crear para artículos nuevos, Editar para actualizaciones y Editar Estado para publicar, despublicar y enviar a la papelera. Los permisos de categoría pueden restringir estas operaciones aún más. Configura los permisos de otros componentes solo si usas sus herramientas.
Abre Usuarios → Gestionar → Nuevo, crea la cuenta dedicada y asígnala a ese grupo. Asegúrate de que la cuenta esté habilitada, activada y no bloqueada.
Vuelve a Sistema → Plugins, abre Usuario - Token de API de Joomla y añade el grupo de este usuario a Grupos de usuarios permitidos, luego guarda. El valor predeterminado normalmente solo permite Super Usuarios; una cuenta recién creada puede no tener pestaña de token de otro modo. No elimines la restricción de grupo solo para que todas las cuentas sean elegibles.

Un permiso Denegado explícito heredado de otro grupo/categoría no se puede corregir permitiéndolo en un grupo hijo. Pide a tu administrador de Joomla que revise los permisos calculados si el acceso sigue denegado. Crear un token de API no otorga permisos adicionales.

3. Copia el token de API de esa cuenta

Inicia sesión en Joomla como la cuenta cuyo token vas a usar. Abre tu propio perfil usando el menú de usuario en la esquina superior derecha del Administrador (Editar cuenta o Perfil, según la versión), y selecciona Token de API de Joomla.

Si Joomla dice que la cuenta aún no tiene token, guarda el perfil y luego vuelve a abrirlo.
Establece Activo en Sí si se muestra ese control, y guarda.
Copia el valor en Token. Esto es lo que pondrás en BEARER_TOKEN a continuación.
Restablecer → Sí, seguido de guardar, reemplaza el token e invalida el anterior.

Solo puedes ver tu propio token. Editar la cuenta de otro usuario como Super Usuario no te permite copiar su token. Si falta la pestaña, revisa el plugin de token y sus grupos permitidos. Consulta la configuración del plugin de token de Joomla y los controles de perfil.

Configura el servidor en tu ordenador

4. Instala Git y uv, luego descarga este repositorio

Usa el ordenador en el que se ejecuta tu aplicación de IA compatible con MCP. Instala Git si git --version no funciona.

Instala uv, que gestionará Python y las dependencias de este servidor. En macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

En Windows, usa PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Vuelve a abrir tu terminal después de la instalación y luego ejecuta estos comandos en cualquier plataforma:

uv --version
git clone https://github.com/nasoma/joomla-mcp-server.git
cd joomla-mcp-server
uv python install 3.14.8
uv sync --locked

Si ya clonaste este repositorio, abre esa carpeta en lugar de clonar de nuevo. uv sync crea el .venv local e instala el servidor. No necesitas activarlo.

5. Pon la URL de tu sitio web y el token en un archivo .env local

En la carpeta del repositorio, copia .env.example a .env.

macOS/Linux:

cp .env.example .env

Windows PowerShell:

Copy-Item .env.example .env

Abre .env en un editor de texto y reemplaza estos valores:

JOOMLA_BASE_URL=https://your-joomla-site.com
BEARER_TOKEN=paste-your-own-joomla-api-token-here
JOOMLA_VERSION=5
JOOMLA_READ_ONLY=true

Establece JOOMLA_VERSION=4 si tu sitio usa Joomla 4. Deja los demás valores de ejemplo sin cambios para la conexión inicial. Configurar JOOMLA_READ_ONLY=true te permite primero confirmar el acceso sin permitir que el asistente cambie tu sitio web.

Usa la URL HTTPS pública de tu sitio. Si Joomla está en una subcarpeta, inclúyela, por ejemplo https://example.com/joomla. No añadas /administrator ni /api/index.php/v1. El servidor añade la ruta de la API por sí mismo. Tu proveedor de alojamiento/cortafuegos debe permitir el acceso a esa API.

Mantén .env privado. Git lo ignora; no lo compartas ni reemplaces los marcadores de posición en este README con un token real. En macOS/Linux, puedes restringir el acceso con chmod 600 .env. El servidor lee las variables de entorno; uv carga este archivo solo cuando pasas --env-file.

6. Confirma que el servidor puede iniciarse

Desde la carpeta del repositorio, ejecuta:

uv run --locked --env-file .env joomla-mcp

Un servidor en ejecución normalmente espera en silencio a un cliente MCP. No abre un navegador, imprime una lista de artículos ni inicia una página web. Pulsa Ctrl+C para detener esta ejecución manual. Iniciar correctamente comprueba la configuración local; la primera solicitud de herramienta en el paso 7 comprueba el acceso a tu sitio web de Joomla.

Conecta tu asistente de IA

7. Añade el servidor a Claude Desktop

Instala y abre Claude Desktop en tu ordenador. Estos ajustes van en su archivo de configuración local, no en un mensaje de chat ni en el campo de URL del conector del sitio web de Claude. Claude Desktop inicia el servidor por ti; no necesitas mantener el paso 6 en ejecución.

Primero, abre una terminal dentro de la carpeta clonada joomla-mcp-server y encuentra las dos rutas:

Marcador de posición en el JSON siguiente	Comando macOS/Linux	Comando Windows PowerShell
`{{PATH_TO_UV}}`	`which uv`	`(Get-Command uv).Source`
`{{PATH_TO_PROJECT}}`	`pwd`	`(Get-Location).Path`

Copia la salida de cada comando. Por ejemplo, which uv podría devolver /Users/you/.local/bin/uv, y pwd podría devolver /Users/you/joomla-mcp-server. Usa tu propia salida, incluida la ruta completa. No uses ~ ni dejes los marcadores de posición sin cambios.

Abre el archivo de configuración:

En macOS, elige Claude → Configuración… en la barra de menú. En Windows, abre Configuración en la aplicación Claude Desktop.
Selecciona Desarrollador → Editar configuración. Esto abre claude_desktop_config.json.
Si el archivo está vacío, pega el JSON completo siguiente. Si ya contiene mcpServers, añade la entrada Joomla Articles MCP dentro de ese objeto y conserva tus servidores existentes.

El archivo se encuentra aquí si necesitas abrirlo manualmente:

Sistema	Archivo de configuración
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

En macOS, usa Finder Ir → Ir a la carpeta… para abrir ~/Library/Application Support/Claude. En Windows, pulsa Win+R, introduce %APPDATA%\Claude y abre el archivo allí. Consulta la guía oficial de MCP local de Claude Desktop.

{
  "mcpServers": {
    "Joomla Articles MCP": {
      "command": "{{PATH_TO_UV}}",
      "args": [
        "--directory",
        "{{PATH_TO_PROJECT}}",
        "run",
        "--locked",
        "--env-file",
        "{{PATH_TO_PROJECT}}/.env",
        "joomla-mcp"
      ]
    }
  }
}

Reemplaza {{PATH_TO_UV}} con la ruta de uv y reemplaza ambas apariciones de {{PATH_TO_PROJECT}} con la ruta del repositorio. Mantén /.env en la segunda aparición; apunta al archivo que creaste en el paso 5. El JSON no debe contener comentarios.

En Windows, usa la ruta completa de uv.exe. Usa barras diagonales, como C:/Users/you/joomla-mcp-server, o duplica cada barra invertida en JSON, como C:\\Users\\you\\joomla-mcp-server. No es necesario copiar ningún token en este JSON; uv lo carga desde tu archivo .env local.

Guarda el archivo, cierra completamente Claude Desktop y luego vuelve a abrirlo. En una conversación, abre Añadir archivos, conectores y más → Conectores → Gestionar conectores y comprueba que Joomla Articles MCP esté disponible. Luego pregunta:

Usa get_joomla_articles para listar los primeros cinco artículos de mi sitio web de Joomla. No cambies nada.

Aprueba la solicitud de lectura si Claude lo pide. Una respuesta correcta contiene IDs/títulos de artículos, o una lista vacía si la cuenta no puede ver artículos. Una lista vacía es diferente de un error de API.

Para otra aplicación MCP, pon el mismo comando y argumentos en su configuración de servidor local/stdio. Este servidor no proporciona una URL MCP HTTP para un conector remoto.

8. Habilita los cambios de contenido cuando estés listo

Después de que la solicitud de lectura tenga éxito, cambia esta línea en .env:

JOOMLA_READ_ONLY=false

Reinicia tu aplicación de IA para que recargue la configuración. Los permisos de Joomla de la cuenta aún controlan qué cambios son posibles. Los artículos nuevos se crean como borradores sin publicar por defecto. Las actualizaciones necesitan el título existente exacto; las operaciones de papelera también necesitan confirmación explícita. Por ejemplo:

Muestra mis categorías de contenido y luego crea un borrador sin publicar llamado “Comprobación de configuración MCP” en la categoría que elija.

Las funciones opcionales se pueden habilitar más tarde: usa JOOMLA_ENABLE_USERS=true para lecturas de usuario filtradas, y activa los plugins de Servicios Web de Joomla correspondientes para otras familias de herramientas.

Elegir una categoría de artículo

create_article y update_article aceptan category_id o category_name. Por ejemplo, “Mover el artículo 87 a Blog” puede usar category_name="Blog"; el servidor resuelve una coincidencia exacta, sin distinción de mayúsculas y minúsculas, con el ID de categoría. Comprueba todas las páginas de categorías disponibles (hasta 1.000 categorías), por lo que una coincidencia en la primera página no puede ocultar un duplicado en una página posterior.

Si no se proporciona ninguna categoría al crear un artículo, no hay coincidencias exactas de nombre o varias categorías comparten el nombre, el servidor no hace ningún cambio y le dice a tu asistente que pregunte qué ID de categoría usar. Los resultados ambiguos incluyen IDs de candidatos e IDs de padres. Proporcionar tanto un nombre como un ID requiere que coincidan. Estos mensajes de aclaración se muestran a través del chat de tu asistente; el servidor no abre una ventana emergente específica del cliente.

Publicar un artículo existente conserva su categoría actual. Para publicar en otra categoría, pide al asistente que lo mueva primero y luego publícalo después de que el movimiento tenga éxito.

Solución de problemas de configuración

Lo que ves	Qué comprobar
No hay pestaña de Token de API de Joomla o el token está en blanco	Habilita Usuario - Token de API de Joomla, incluye el grupo de la cuenta en Grupos de usuarios permitidos, inicia sesión con esa cuenta, guarda y vuelve a abrir su perfil.
HTTP 401	Comprueba Autenticación de API - Token de Joomla de Servicios Web, el token copiado y su configuración de Activo. Si el token se restableció, actualiza `.env` y reinicia el cliente.
HTTP 403	Comprueba el permiso de Inicio de sesión de Servicios Web de la cuenta, la elegibilidad del grupo y los permisos de componente/categoría para la operación solicitada.
HTTP 500	La herramienta incluye títulos/detalles de errores JSON de Joomla cuando están disponibles, con credenciales y rutas redactadas. Lee el artículo antes de reintentar una escritura fallida porque es posible que ya se haya guardado. Si Joomla solo informa un error interno del servidor, pregunta a tu proveedor de alojamiento por la entrada correspondiente en el registro de errores de PHP; el stderr local de MCP solo muestra el estado HTTP.
HTTP 404	Comprueba la URL de la raíz/subcarpeta del sitio y el complemento de Servicios Web correspondiente. El host debe enrutar `/api/index.php/v1/...` a Joomla en lugar de bloquearlo.
Fallo de red o tiempo de espera	Comprueba que tu computadora pueda acceder a la URL HTTPS del sitio y que el host/cortafuegos permita solicitudes de API.
Respuesta de Joomla no válida / JSON esperado	Es posible que se haya devuelto una página de inicio de sesión, un error de alojamiento o un desafío de cortafuegos en lugar del JSON de la API. Comprueba la ruta de la API con tu host.
Error de configuración sobre URL/token	Confirma que `.env` contiene ambos valores y que el comando del cliente incluye la ruta absoluta correcta de `--env-file`.
Servidor ausente en tu aplicación de IA	Comprueba la sintaxis JSON, las rutas absolutas y `uv --version`; reinicia completamente la aplicación e inspecciona sus registros de errores de MCP.
El servidor espera en silencio en la terminal	Esto es esperado para stdio; conecta tu aplicación de IA como se describe en el paso 7.
Escrituras deshabilitadas	Cambia JOOMLA_READ_ONLY a false en `.env`, luego reinicia la aplicación.

La guía de Servicios Web de Joomla explica los requisitos previos de la API y la cuenta. Nunca publiques tu token al pedir ayuda de configuración.

Herramientas

Área	Herramientas
Artículos	`get_joomla_articles`, `get_joomla_article`, `create_article`, `update_article`, `manage_article_state`, `move_article_to_trash`
Categorías	`get_joomla_categories`, `get_joomla_category`, `create_category`, `update_category`, `delete_category`
Etiquetas	`get_joomla_tags`, `get_joomla_tag`, `create_tag`, `update_tag`, `delete_tag`; asignación de etiquetas a artículos mediante `update_article(tags=[IDs])`
Campos	`get_joomla_fields`, `get_joomla_field`, `create_field`, `update_field`, `delete_field`, `get_joomla_field_groups`, `get_joomla_field_group`, `create_field_group`, `update_field_group`, `delete_field_group`, `get_article_fields`, `update_article_fields`
Medios	`get_joomla_media`, `get_joomla_media_file`, `upload_media`, `update_article_images`
Menús del sitio	`get_joomla_menus`, `get_joomla_menu`, `create_menu`, `update_menu`, `delete_menu`, `get_joomla_menu_items`, `get_joomla_menu_item`, `create_menu_item`, `update_menu_item`, `delete_menu_item`
Módulos del sitio	`get_joomla_modules`, `get_joomla_module`, `create_custom_module`, `update_module`, `delete_module`
Usuarios (opt-in)	`get_joomla_users`, `get_joomla_user`; solo lectura

Los esquemas de entrada de las herramientas contienen tipos, límites y descripciones. Los IDs deben ser enteros positivos; los booleanos y las cadenas numéricas se rechazan. Las listas tienen un valor predeterminado de 20 filas y permiten como máximo 100. Para artículos, usa los filtros de búsqueda/category_id/state/tag_id y sigue pagination.next_offset. El contenido de la lista de artículos se omite por defecto; solicita include_content=true o la consulta de detalle. Los directorios de medios están limitados por bytes y se dividen localmente porque Joomla no los pagina.

Los resultados exitosos son objetos estructurados con ok: true, data normalizado y opcionalmente pagination, updated_fields o changed. Los IDs de recursos en los resultados son cadenas; proporciona los IDs como enteros al llamar a una herramienta. Los errores son errores de herramienta MCP (is_error=true), con mensajes seguros y limitados. Los cuerpos de la API, las credenciales y las excepciones de red sin procesar no se devuelven.

Configuración

Variable	Predeterminado	Significado
`JOOMLA_BASE_URL`, `BEARER_TOKEN`	Requerido	Raíz HTTPS del sitio y token secreto
`JOOMLA_VERSION`	`5`	Versión principal compatible, `4` o `5`; las herramientas usan su contrato de API común
`JOOMLA_READ_ONLY`	`false`	Rechazar mutaciones
`JOOMLA_ALLOW_TRUSTED_HTML`	`false`	Permitir HTML confiable seleccionado explícitamente
`JOOMLA_ENABLE_USERS`	`false`	Registrar herramientas de lectura de usuarios filtradas
`JOOMLA_ALLOW_LOCAL_HTTP`	`false`	Excepción de desarrollo de bucle invertido
`JOOMLA_TIMEOUT`	`20`	Tiempo de espera por solicitud, en segundos (máximo 120)
`JOOMLA_READ_RETRIES`	`2`	Intentos adicionales de lectura segura (0–3); las escrituras nunca se reintentan
`JOOMLA_MAX_RESPONSE_BYTES`	`2000000`	Máximo de bytes de respuesta de API decodificados
`JOOMLA_MAX_UPLOAD_BYTES`	`5000000`	Máximo de bytes de carga de imagen decodificados

Los valores booleanos aceptan true/false o 1/0. Las redirecciones y la búsqueda de entorno de proxy están deshabilitadas. Los valores Retry-After de lectura superiores a cinco segundos devuelven un fallo para que el llamador pueda reprogramar.

Licencia

MIT; consulta LICENSE.