Joomla MCP

Joomla MCP 服务

将 AI 助手连接到现有的 Joomla 4 或 5 网站，使其能够读取和管理文章、分类、标签及其他受支持的网站内容。

你需要配置两个地方：Joomla 网站和运行 AI 助手的计算机。此 Python 服务在你的计算机上运行，并通过 HTTPS 调用 Joomla 内置的 Web Services API。你无需将此代码库安装为 Joomla 扩展，也无需将其上传到 Web 主机。你的 AI 应用必须支持使用 stdio 的本地 MCP 服务；以下示例使用 Claude Desktop。

设置 Joomla 网站

1. 启用所需插件

以超级用户身份登录 Joomla Administrator。打开系统 → 管理 → 插件（或系统 → 插件，具体取决于你的管理员界面布局）。搜索并启用：

插件	用途
API Authentication - Web Services Joomla Token	使用令牌验证 API 请求
User - Joomla API Token	创建和管理用户的 API 令牌
Web Services - Content	文章、内容分类和文章字段

请先启用这三个插件。如果你想使用其他工具，也请启用相应的 Web Services - Tags、Media、Menus、Modules 或 Users 插件。媒体工具需要 Joomla 4.1 或更高版本。自定义字段还需要 Joomla 的 Fields 组件和字段插件。

2. 选择助手要使用的 Joomla 账户

API 令牌属于某个 Joomla 用户。请求将使用该用户的权限。请为此连接使用专用账户，而不要使用日常使用的超级用户账户。

创建专用账户：

1. 打开用户 → 用户组 → 新建，并创建一个组，例如 MCP Content Editors。若要从权限受限的配置开始，请选择 Registered 作为父组。
2. 打开系统 → 全局配置 → 权限，选择你的用户组，并允许Web 服务登录（core.login.api）。同时允许管理员登录，这样该账户才能打开自己的个人资料并复制令牌。检查计算后的权限是否显示为“允许”；不要设置超级用户访问权限。
3. 若要管理文章，请打开内容 → 文章 → 选项 → 权限。为该组授予文章组件的访问管理界面权限，然后只启用所需操作：新建文章需创建，更新文章需编辑，发布、取消发布和移至回收站需编辑状态。分类权限可进一步限制这些操作。仅在使用其他组件的工具时，才配置其权限。
4. 打开用户 → 管理 → 新建，创建专用账户并将其分配到该组。确保账户已启用、已激活且未被阻止。
5. 返回系统 → 插件，打开 User - Joomla API Token，将此用户所在的组添加到允许的用户组，然后保存。默认设置通常只允许超级用户；否则，新建账户可能不会显示令牌选项卡。不要仅为让所有账户都符合条件而清除组限制。

从其他组或分类继承的明确“拒绝”权限，无法通过在子组中允许该权限来解决。如果访问仍被拒绝，请让 Joomla 管理员检查计算后的权限。创建 API 令牌不会授予额外权限。

3. 复制该账户的 API 令牌

使用你要用其令牌的账户登录 Joomla。通过 Administrator 右上角的用户菜单打开自己的个人资料 （根据版本不同，选择 Edit Account 或 Profile），然后选择 Joomla API Token。

• 如果 Joomla 提示该账户尚无令牌，请保存个人资料，然后重新打开。
• 如果页面显示 Active 控件，将其设为 Yes 并保存。
• 复制 Token 中的值。这就是你将在下文填入 BEARER_TOKEN 的内容。
• 将 Reset → Yes，然后保存，即可替换令牌并使旧令牌失效。

你只能查看自己的令牌。以 Super User 身份编辑其他用户的账户，也无法复制其令牌。如果缺少此标签页，请检查令牌插件及其允许的用户组。 请参阅 Joomla 的令牌插件设置 和个人资料控件。

在你的计算机上设置服务

4. 安装 Git 和 uv，然后下载此代码库

请使用运行 MCP 兼容 AI 应用的计算机。如果 git --version 无法运行，请安装 Git。

安装 uv，用于管理 Python 和此服务的依赖项。在 macOS/Linux 上：

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

在 Windows 上，使用 PowerShell：

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

安装后重新打开终端，然后在任一平台运行以下命令：

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

如果你已经克隆了此代码库，请改为打开该文件夹，无需再次克隆。 uv sync 会创建本地 .venv 并安装服务。你无需激活它。

5. 将网站 URL 和令牌填入本地 .env 文件

在代码库文件夹中，将 .env.example 复制为 .env。

macOS/Linux：

cp .env.example .env

Windows PowerShell：

Copy-Item .env.example .env

使用文本编辑器打开 .env，并替换以下值：

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

如果你的网站使用 Joomla 4，请设置 JOOMLA_VERSION=4。首次连接时，其他示例设置保持不变。 设置 JOOMLA_READ_ONLY=true，即可先确认访问权限，而不允许助手更改你的网站。

请使用网站公开的 HTTPS URL。如果 Joomla 安装在子文件夹中，请将其包含在 URL 中，例如 https://example.com/joomla。不要在 URL 后追加 /administrator 或 /api/index.php/v1。 服务会自行添加 API 路径。你的主机/防火墙必须允许访问该 API。

请妥善保管 .env。Git 会忽略此文件；请勿分享，也不要将本 README 中的占位内容替换为真实令牌。在 macOS/Linux 上，你可以使用 chmod 600 .env 限制访问权限。 服务会读取环境变量；只有在传入 --env-file 时，uv 才会加载此文件。

6. 确认服务可以启动

在代码库文件夹中运行：

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

正常运行的服务通常会安静地等待 MCP 客户端。它不会打开浏览器、打印文章列表或启动网页。按 Ctrl+C 停止此次手动运行。 成功启动表示本地配置正常；第 7 步中的首次工具请求会检查是否能访问你的 Joomla 网站。

连接你的 AI 助手

7. 将服务添加到 Claude Desktop

在电脑上安装并打开 Claude Desktop。这些设置要写入本地配置文件，而不是聊天消息或 Claude 网站的连接器 URL 输入框。Claude Desktop 会为你启动服务；无需让第 6 步继续运行。

首先，在已克隆的 joomla-mcp-server 文件夹内打开终端，并查找以下两个路径：

JSON 中的占位符	macOS/Linux 命令	Windows PowerShell 命令
{{PATH_TO_UV}}	which uv	(Get-Command uv).Source
{{PATH_TO_PROJECT}}	pwd	(Get-Location).Path

复制每条命令的输出。例如，which uv 可能会返回 /Users/you/.local/bin/uv，而 pwd 可能会返回 /Users/you/joomla-mcp-server。 使用你自己的输出，包括完整路径。不要使用 ~，也不要保留占位符。

打开配置文件：

1. 在 macOS 上，从菜单栏选择 Claude → Settings…。在 Windows 上，打开 Claude Desktop 应用中的 Settings。
2. 选择 Developer → Edit Config。这会打开 claude_desktop_config.json。
3. 如果文件为空，粘贴下面的完整 JSON。如果文件中已包含 mcpServers，请在该对象内添加 Joomla Articles MCP 条目，并保留现有服务。

如需手动打开，配置文件位于：

系统	配置文件
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

在 macOS 上，使用 Finder 的 Go → Go to Folder… 打开 ~/Library/Application Support/Claude。 在 Windows 上，按 Win+R，输入 %APPDATA%\Claude，然后在那里打开文件。 请参阅官方的 Claude Desktop 本地 MCP 指南。

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

将 {{PATH_TO_UV}} 替换为 uv 路径，并将 {{PATH_TO_PROJECT}} 的两处都替换为仓库路径。保留第二处末尾的 /.env； 它指向你在第 5 步创建的文件。JSON 中不得包含注释。

在 Windows 上，使用完整的 uv.exe 路径。在 JSON 中使用正斜杠，例如 C:/Users/you/joomla-mcp-server，或者将每个反斜杠重复两次，例如 C:\\Users\\you\\joomla-mcp-server。无需将令牌复制到此 JSON 中； uv 会从本地 .env 文件加载令牌。

保存文件，完全退出 Claude Desktop，然后重新打开。在对话中，打开 Add files, connectors, and more → Connectors → Manage connectors，并确认 Joomla Articles MCP 可用。然后提问：

使用 get_joomla_articles 列出我的 Joomla 网站上的前五篇文章。不要更改任何内容。

如果 Claude 询问，请批准读取请求。成功的响应会包含文章 ID/标题；如果该账号看不到任何文章，则会返回空列表。空列表与 API 错误不同。

对于其他 MCP 应用，请在其本地/stdio 服务配置中填写相同的命令和参数。此服务不提供供远程连接器使用的 HTTP MCP URL。

8. 准备好后启用内容修改

读取请求成功后，更改 .env 中的这一行：

JOOMLA_READ_ONLY=false

重启 AI 应用，使其重新加载配置。账号的 Joomla 权限仍决定哪些更改可以执行。新文章默认保存为未发布的草稿。更新文章需要提供完全匹配的现有标题；移入回收站的操作还需要明确确认。例如：

显示我的内容分类，然后在我选择的分类中创建一篇名为“MCP setup check”的未发布草稿。

可稍后启用可选功能：使用 JOOMLA_ENABLE_USERS=true 启用经过筛选的用户读取，并为其他工具系列启用对应的 Joomla Web Services 插件。

选择文章分类

create_article 和 update_article 可接受 category_id 或 category_name。 例如，“将文章 87 移至 Blog”可以使用 category_name="Blog"；服务会解析名称完全匹配且不区分大小写的分类 ID。它会检查所有可用的分类页面 （最多 1,000 个分类），因此第一页上的匹配项不会掩盖后续页面中的重复项。

创建文章时未提供分类、没有名称完全匹配项，或多个分类名称相同，服务都不会进行更改，并会提示你的助手询问要使用哪个分类 ID。存在歧义的结果会包含候选 ID 和父级 ID。 同时提供名称和 ID 时，两者必须一致。这些澄清消息会通过助手的聊天界面显示；服务不会打开特定客户端的弹出窗口。

发布现有文章时会保留其当前分类。若要在其他分类中发布，请先让助手移动文章，待移动成功后再发布。

设置故障排除

你看到的情况	检查内容
没有 Joomla API Token 选项卡或令牌为空	启用 User - Joomla API Token，将该账户所属的组加入 Allowed User Groups，以该账户登录，保存并重新打开其个人资料。
HTTP 401	检查 API Authentication - Web Services Joomla Token、复制的令牌及其 Active 设置。如果令牌已重置，请更新 .env 并重启客户端。
HTTP 403	检查账户的 Web Services Login 权限、组资格，以及所请求操作对应的组件/分类权限。
HTTP 500	工具会在可用时附上 Joomla JSON 错误标题/详情，并对凭据和路径进行脱敏。重试失败的写入前，请先查看文章，因为它可能已经保存。如果 Joomla 只报告内部服务器错误，请向主机提供商索取对应的 PHP 错误日志条目；本地 MCP stderr 只会显示 HTTP 状态。
HTTP 404	检查网站根目录/子文件夹 URL 及对应的 Web Services 插件。主机必须将 /api/index.php/v1/... 路由到 Joomla，而不是拦截该路径。
网络故障或超时	检查你的计算机能否访问网站的 HTTPS URL，以及主机/防火墙是否允许 API 请求。
Joomla 响应无效/应为 JSON	返回的可能是登录页面、主机错误或防火墙质询，而不是 API JSON。请向主机提供商检查 API 路由。
URL/令牌配置错误	确认 .env 包含这两个值，且客户端命令包含正确的绝对 --env-file 路径。
AI 应用中缺少服务	检查 JSON 语法、绝对路径和 uv --version；彻底重启应用并检查其 MCP 错误日志。
服务在终端中无响应地等待	这是 stdio 模式的预期行为；请按步骤 7 中的说明连接 AI 应用。
已禁用写入	在 .env 中将 JOOMLA_READ_ONLY 改为 false，然后重启应用。

Joomla 的 Web Services 指南 介绍了 API 和账户的前置条件。寻求设置帮助时，切勿公开你的令牌。

工具

区域	工具
文章	get_joomla_articles、get_joomla_article、create_article、update_article、manage_article_state、move_article_to_trash
分类	get_joomla_categories、get_joomla_category、create_category、update_category、delete_category
标签	get_joomla_tags、get_joomla_tag、create_tag、update_tag、delete_tag；通过 update_article(tags=[IDs]) 为文章分配标签
字段	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
媒体	get_joomla_media、get_joomla_media_file、upload_media、update_article_images
网站菜单	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
网站模块	get_joomla_modules、get_joomla_module、create_custom_module、update_module、delete_module
用户（选择启用）	get_joomla_users、get_joomla_user；只读

工具输入架构包含类型、范围和描述。ID 必须是正整数； 布尔值和数字字符串会被拒绝。列表默认返回 20 行，最多允许 100 行。 对于文章，请使用 search/category_id/state/tag_id 筛选条件，并跟进 pagination.next_offset。 默认不包含文章列表内容；如需获取，请请求 include_content=true 或查询详情。 媒体目录受字节数限制，并在本地分段处理，因为 Joomla 不支持对其分页。

成功结果是结构化对象，包含 ok: true、标准化后的 data，以及可选的 pagination、updated_fields 或 changed。结果中的资源 ID 是字符串；调用工具时请将 ID 作为整数传入。错误会作为 MCP 工具错误返回（is_error=true），并附带安全且长度受限的消息。不会返回 API 请求正文、凭据或原始网络异常。

配置

变量	默认值	含义
JOOMLA_BASE_URL、BEARER_TOKEN	必填	HTTPS 站点根地址和密钥令牌
JOOMLA_VERSION	5	支持的主版本，4 或 5；工具使用通用 API 契约
JOOMLA_READ_ONLY	false	拒绝修改操作
JOOMLA_ALLOW_TRUSTED_HTML	false	允许明确选用的可信 HTML
JOOMLA_ENABLE_USERS	false	注册经过筛选的用户读取工具
JOOMLA_ALLOW_LOCAL_HTTP	false	允许回环地址开发例外
JOOMLA_TIMEOUT	20	每个请求的超时时间，单位为秒（最长 120 秒）
JOOMLA_READ_RETRIES	2	安全读取操作的额外尝试次数（0–3）；写入操作不会重试
JOOMLA_MAX_RESPONSE_BYTES	2000000	解码后的 API 响应最大字节数
JOOMLA_MAX_UPLOAD_BYTES	5000000	解码后的图片上传最大字节数

布尔值接受 true/false 或 1/0。重定向和代理环境变量查找均已禁用。 读取时，若 Retry-After 值超过 5 秒，则会返回失败，以便调用方重新安排请求。

许可证

MIT；参见 LICENSE。