Joomla MCP Server

Crie artigos em um site Joomla usando sua API.

Documentação

Joomla MCP Server

Conecte um assistente de IA ao seu site Joomla 4 ou 5 existente para que ele possa ler e gerenciar artigos, categorias, tags e outros conteúdos suportados do site.

Você configura dois lugares: seu site Joomla e o computador que executa seu assistente de IA. Este servidor Python roda no seu computador e chama a API de Web Services integrada do Joomla via HTTPS. Você não instala este repositório como uma extensão do Joomla nem o envia para seu servidor de hospedagem. Seu aplicativo de IA deve suportar servidores MCP locais usando stdio; o exemplo abaixo usa o Claude Desktop.

Configure seu site Joomla

1. Ative os plugins necessários

Entre no Administrador do Joomla como Super Usuário. Abra Sistema → Gerenciar → Plugins (ou Sistema → Plugins, dependendo do layout do administrador). Pesquise e ative:

Plugin	Necessário para
Autenticação de API - Token Web Services Joomla	Autenticar solicitações de API com seu token
Usuário - Token de API do Joomla	Criar e gerenciar o token de API de um usuário
Web Services - Conteúdo	Artigos, categorias de conteúdo e campos de artigo

Comece com esses três. Se quiser ferramentas adicionais, ative também os plugins correspondentes Web Services - Tags, Mídia, Menus, Módulos ou Usuários. As ferramentas de mídia exigem Joomla 4.1 ou posterior. Campos personalizados também precisam do componente Fields do Joomla e dos plugins de campos.

2. Escolha a conta do Joomla que o assistente usará

O token de API pertence a um usuário do Joomla. As solicitações têm as permissões desse usuário. Use uma conta dedicada para esta conexão, em vez da sua conta de Super Usuário do dia a dia.

Para uma conta dedicada:

Abra Usuários → Grupos → Novo e crie um grupo como MCP Content Editors. Para um ponto de partida restrito, selecione Registrado como grupo pai.
Abra Sistema → Configuração Global → Permissões, selecione seu grupo e permita Login de Web Services (core.login.api). Também permita Login de Administrador para que esta conta possa abrir seu próprio perfil e copiar seu token. Verifique se as permissões calculadas mostram Permitido; deixe o acesso de Super Usuário não definido.
Para gerenciamento de artigos, abra Conteúdo → Artigos → Opções → Permissões. Dê ao grupo Acesso à Interface de Administração para o componente Artigos e, em seguida, apenas as ações necessárias: Criar para novos artigos, Editar para atualizações e Editar Estado para publicar, despublicar e mover para a lixeira. As permissões de categoria podem restringir ainda mais essas operações. Configure as permissões de outros componentes somente se você usar suas ferramentas.
Abra Usuários → Gerenciar → Novo, crie a conta dedicada e atribua-a a esse grupo. Certifique-se de que a conta esteja ativada, ativa e não bloqueada.
Volte a Sistema → Plugins, abra Usuário - Token de API do Joomla e adicione o grupo deste usuário em Grupos de Usuários Permitidos e salve. O padrão geralmente permite apenas Super Usuários; uma conta recém-criada pode não ter a aba de token caso contrário. Não remova a restrição de grupo apenas para tornar todas as contas elegíveis.

Uma permissão explicitamente Negada herdada de outro grupo/categoria não pode ser corrigida permitindo-a em um grupo filho. Peça ao administrador do Joomla para verificar as permissões calculadas se o acesso ainda for negado. Criar um token de API não concede permissões adicionais.

3. Copie o token de API dessa conta

Entre no Joomla como a conta cujo token você usará. Abra seu próprio perfil usando o menu do usuário no canto superior direito do Administrador (Editar Conta ou Perfil, dependendo da versão) e selecione Token de API do Joomla.

Se o Joomla disser que a conta ainda não tem token, salve o perfil e reabra-o.
Defina Ativo como Sim se esse controle for exibido e salve.
Copie o valor em Token. É isso que você colocará em BEARER_TOKEN abaixo.
Redefinir → Sim, seguido de salvar, substitui o token e invalida o antigo.

Você só pode visualizar seu próprio token. Editar a conta de outro usuário como Super Usuário não permite copiar o token dele. Se a aba estiver ausente, verifique o plugin de token e seus grupos permitidos. Consulte as configurações do plugin de token do Joomla e os controles de perfil.

Configure o servidor no seu computador

4. Instale Git e uv, depois baixe este repositório

Use o computador no qual seu aplicativo de IA compatível com MCP é executado. Instale Git se git --version não funcionar.

Instale uv, que gerenciará o Python e as dependências deste servidor. No macOS/Linux:

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

No Windows, use o PowerShell:

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

Reabra seu terminal após a instalação e execute estes comandos em qualquer 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

Se você já clonou este repositório, abra essa pasta em vez de clonar novamente. uv sync cria o .venv local e instala o servidor. Você não precisa ativá-lo.

5. Coloque a URL do seu site e o token em um arquivo .env local

Na pasta do repositório, copie .env.example para .env.

macOS/Linux:

cp .env.example .env

Windows PowerShell:

Copy-Item .env.example .env

Abra .env em um editor de texto e substitua estes 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

Defina JOOMLA_VERSION=4 se seu site usa Joomla 4. Deixe as outras configurações de exemplo inalteradas para a conexão inicial. Definir JOOMLA_READ_ONLY=true permite confirmar primeiro o acesso sem permitir que o assistente altere seu site.

Use a URL HTTPS pública do seu site. Se o Joomla estiver em uma subpasta, inclua-a, por exemplo https://example.com/joomla. Não acrescente /administrator ou /api/index.php/v1. O servidor adiciona o caminho da API por conta própria. Seu host/firewall deve permitir acesso a essa API.

Mantenha .env privado. Ele é ignorado pelo Git; não o compartilhe nem substitua os placeholders neste README por um token real. No macOS/Linux, você pode restringir o acesso com chmod 600 .env. O servidor lê variáveis de ambiente; uv carrega este arquivo somente quando você passa --env-file.

6. Confirme que o servidor pode iniciar

Na pasta do repositório, execute:

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

Um servidor em execução normalmente aguarda silenciosamente um cliente MCP. Ele não abre um navegador, imprime uma lista de artigos nem inicia uma página web. Pressione Ctrl+C para interromper esta execução manual. Iniciar com sucesso verifica a configuração local; a primeira solicitação de ferramenta na etapa 7 verifica o acesso ao seu site Joomla.

Conecte seu assistente de IA

7. Adicione o servidor ao Claude Desktop

Instale e abra o Claude Desktop no seu computador. Essas configurações vão no arquivo de configuração local, não em uma mensagem de chat nem no campo de URL do conector do site do Claude. O Claude Desktop inicia o servidor para você; você não precisa manter a etapa 6 em execução.

Primeiro, abra um terminal dentro da pasta joomla-mcp-server clonada e encontre os dois caminhos:

Placeholder no JSON abaixo	Comando macOS/Linux	Comando Windows PowerShell
`{{PATH_TO_UV}}`	`which uv`	`(Get-Command uv).Source`
`{{PATH_TO_PROJECT}}`	`pwd`	`(Get-Location).Path`

Copie a saída de cada comando. Por exemplo, which uv pode retornar /Users/you/.local/bin/uv, e pwd pode retornar /Users/you/joomla-mcp-server. Use sua própria saída, incluindo o caminho completo. Não use ~ nem deixe os placeholders inalterados.

Abra o arquivo de configuração:

No macOS, escolha Claude → Configurações… na barra de menus. No Windows, abra Configurações no aplicativo Claude Desktop.
Selecione Desenvolvedor → Editar Configuração. Isso abre claude_desktop_config.json.
Se o arquivo estiver vazio, cole o JSON completo abaixo. Se já contiver mcpServers, adicione a entrada Joomla Articles MCP dentro desse objeto e mantenha seus servidores existentes.

O arquivo fica aqui se você precisar abri-lo manualmente:

Sistema	Arquivo de configuração
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

No macOS, use o Finder Ir → Ir para a Pasta… para abrir ~/Library/Application Support/Claude. No Windows, pressione Win+R, digite %APPDATA%\Claude e abra o arquivo lá. Consulte o guia oficial de MCP local do 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"
      ]
    }
  }
}

Substitua {{PATH_TO_UV}} pelo caminho do uv e substitua ambas as ocorrências de {{PATH_TO_PROJECT}} pelo caminho do repositório. Mantenha /.env na segunda ocorrência; ele aponta para o arquivo que você criou na etapa 5. O JSON não deve conter comentários.

No Windows, use o caminho completo do uv.exe. Use barras normais, como C:/Users/you/joomla-mcp-server, ou duplique cada barra invertida no JSON, como C:\\Users\\you\\joomla-mcp-server. Nenhum token precisa ser copiado para este JSON; uv o carrega do seu arquivo .env local.

Salve o arquivo, saia completamente do Claude Desktop e reabra-o. Em uma conversa, abra Adicionar arquivos, conectores e mais → Conectores → Gerenciar conectores e verifique se Joomla Articles MCP está disponível. Então pergunte:

Use get_joomla_articles para listar os primeiros cinco artigos do meu site Joomla. Não altere nada.

Aprove a solicitação de leitura se o Claude pedir. Uma resposta bem-sucedida contém IDs/títulos de artigos, ou uma lista vazia se a conta não puder ver artigos. Uma lista vazia é diferente de um erro de API.

Para outro aplicativo MCP, coloque o mesmo comando e argumentos na configuração do servidor local/stdio. Este servidor não fornece uma URL MCP HTTP para um conector remoto.

8. Ative alterações de conteúdo quando estiver pronto

Depois que a solicitação de leitura for bem-sucedida, altere esta linha em .env:

JOOMLA_READ_ONLY=false

Reinicie seu aplicativo de IA para que ele recarregue a configuração. As permissões do Joomla da conta ainda controlam quais alterações são possíveis. Novos artigos são criados como rascunhos não publicados por padrão. Atualizações exigem o título existente exato; operações de lixeira também exigem confirmação explícita. Por exemplo:

Mostre minhas categorias de conteúdo e crie um rascunho não publicado chamado “Verificação de configuração MCP” na categoria que eu escolher.

Recursos opcionais podem ser ativados depois: use JOOMLA_ENABLE_USERS=true para leituras de usuário filtradas e ative os plugins de Web Services do Joomla correspondentes para outras famílias de ferramentas.

Escolhendo uma categoria de artigo

create_article e update_article aceitam category_id ou category_name. Por exemplo, “Mover artigo 87 para Blog” pode usar category_name="Blog"; o servidor resolve uma correspondência exata, sem diferenciar maiúsculas de minúsculas, para o ID da categoria. Ele verifica todas as páginas de categorias disponíveis (até 1.000 categorias), portanto, uma correspondência na primeira página não pode ocultar uma duplicata em uma página posterior.

Se nenhuma categoria for fornecida ao criar um artigo, nenhum nome corresponder exatamente ou várias categorias compartilharem o nome, o servidor não faz alterações e informa ao seu assistente para perguntar qual ID de categoria usar. Resultados ambíguos incluem IDs de candidatos e IDs de pais. Fornecer nome e ID exige que eles concordem. Essas mensagens de esclarecimento são mostradas pelo chat do seu assistente; o servidor não abre um popup específico do cliente.

Publicar um artigo existente mantém sua categoria atual. Para publicar em outra categoria, peça ao assistente para movê-lo primeiro e depois publicá-lo após a movimentação ser bem-sucedida.

Solução de problemas de configuração

O que você vê	O que verificar
Sem aba Joomla API Token ou token em branco	Ative o plugin User - Joomla API Token, inclua o grupo da conta em Allowed User Groups, faça login com essa conta, salve e reabra o perfil.
HTTP 401	Verifique o plugin API Authentication - Web Services Joomla Token, o token copiado e sua configuração Active. Se o token foi redefinido, atualize `.env` e reinicie o cliente.
HTTP 403	Verifique a permissão Web Services Login da conta, a elegibilidade do grupo e as permissões de componente/categoria para a operação solicitada.
HTTP 500	A ferramenta inclui títulos/detalhes de erro JSON do Joomla quando disponíveis, com credenciais e caminhos ocultos. Leia o artigo antes de tentar novamente uma escrita com falha, pois ela pode já ter sido salva. Se o Joomla apenas relatar um erro interno do servidor, peça ao seu provedor a entrada correspondente no log de erros do PHP; o stderr local do MCP mostra apenas o status HTTP.
HTTP 404	Verifique a URL da raiz/subpasta do site e o plugin Web Services correspondente. O host deve rotear `/api/index.php/v1/...` para o Joomla em vez de bloqueá-lo.
Falha de rede ou timeout	Verifique se o seu computador consegue acessar a URL HTTPS do site e se o host/firewall permite solicitações de API.
Resposta inválida do Joomla / JSON esperado	Uma página de login, erro de hospedagem ou desafio de firewall pode ter sido retornado em vez do JSON da API. Verifique a rota da API com o seu host.
Erro de configuração sobre URL/token	Confirme que `.env` contém ambos os valores e que o comando do cliente inclui o caminho absoluto correto de `--env-file`.
Servidor ausente no seu aplicativo de IA	Verifique a sintaxe JSON, caminhos absolutos e `uv --version`; reinicie completamente o aplicativo e inspecione os logs de erro do MCP.
Servidor aguarda silenciosamente no terminal	Isso é esperado para stdio; conecte seu aplicativo de IA conforme descrito no passo 7.
Escritas desabilitadas	Altere JOOMLA_READ_ONLY para false em `.env` e reinicie o aplicativo.

O guia de Web Services do Joomla explica os pré-requisitos da API e da conta. Nunca publique seu token ao pedir ajuda de configuração.

Ferramentas

Área	Ferramentas
Artigos	`get_joomla_articles`, `get_joomla_article`, `create_article`, `update_article`, `manage_article_state`, `move_article_to_trash`
Categorias	`get_joomla_categories`, `get_joomla_category`, `create_category`, `update_category`, `delete_category`
Tags	`get_joomla_tags`, `get_joomla_tag`, `create_tag`, `update_tag`, `delete_tag`; atribuição de tag a artigos via `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`
Mídia	`get_joomla_media`, `get_joomla_media_file`, `upload_media`, `update_article_images`
Menus do site	`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 do site	`get_joomla_modules`, `get_joomla_module`, `create_custom_module`, `update_module`, `delete_module`
Usuários (opt-in)	`get_joomla_users`, `get_joomla_user`; somente leitura

Os esquemas de entrada das ferramentas contêm tipos, limites e descrições. IDs devem ser inteiros positivos; booleanos e strings numéricas são rejeitados. Listas padrão têm 20 linhas e permitem no máximo 100. Para artigos, use os filtros search/category_id/state/tag_id e siga pagination.next_offset. O conteúdo da lista de artigos é omitido por padrão; solicite include_content=true ou consulta de detalhes. Diretórios de mídia têm limite de bytes e são divididos localmente porque o Joomla não os pagina.

Resultados de sucesso são objetos estruturados com ok: true, data normalizado e opcionalmente pagination, updated_fields ou changed. IDs de recursos nos resultados são strings; forneça IDs como inteiros ao chamar uma ferramenta. Erros são erros de ferramenta MCP (is_error=true), com mensagens seguras e limitadas. Corpos de API, credenciais e exceções brutas de rede não são retornados.

Configuração

Variável	Padrão	Significado
`JOOMLA_BASE_URL`, `BEARER_TOKEN`	Obrigatório	Raiz HTTPS do site e token secreto
`JOOMLA_VERSION`	`5`	Versão principal suportada, `4` ou `5`; as ferramentas usam seu contrato de API comum
`JOOMLA_READ_ONLY`	`false`	Rejeitar mutações
`JOOMLA_ALLOW_TRUSTED_HTML`	`false`	Permitir HTML confiável explicitamente selecionado
`JOOMLA_ENABLE_USERS`	`false`	Registrar ferramentas de leitura de usuário filtradas
`JOOMLA_ALLOW_LOCAL_HTTP`	`false`	Exceção de desenvolvimento em loopback
`JOOMLA_TIMEOUT`	`20`	Timeout por solicitação, em segundos (máximo 120)
`JOOMLA_READ_RETRIES`	`2`	Tentativas extras de leitura segura (0–3); escritas nunca tentam novamente
`JOOMLA_MAX_RESPONSE_BYTES`	`2000000`	Máximo de bytes decodificados de resposta da API
`JOOMLA_MAX_UPLOAD_BYTES`	`5000000`	Máximo de bytes decodificados de upload de imagem

Valores booleanos aceitam true/false ou 1/0. Redirecionamentos e consulta de proxy por ambiente estão desabilitados. Valores Retry-After acima de cinco segundos retornam falha para que o chamador possa reagendar.

Licença

MIT; veja LICENSE.