Halo怎么接入MCP？AI管理文章、评论和附件配置教程

管理Halo网站时，查找旧文章、整理标签、修改草稿，往往需要在后台切换多个页面。安装MCP Server插件后，这些操作可以交给AI客户端处理。例如，让AI查找某个主题的文章，或先写好一篇草稿，检查后再发布。

MCP服务端运行在Halo中，不需要另外安装Halo CLI。完成插件安装、密钥授权和客户端配置后，就可以通过对话调用站点管理工具。

一、Halo MCP Server是什么？

MCP即模型上下文协议，用于连接AI客户端与外部工具。Halo MCP Server插件将文章、评论、附件等管理功能提供为MCP工具，客户端连接后，可以在授权范围内执行相应操作。

插件提供的连接地址采用以下格式。

https://你的域名/mcp

这个地址是供MCP客户端连接的服务端点，不是网站后台登录页面。访问时需要使用管理员创建的密钥。

目前支持的功能如下。

管理对象	支持操作
文章、独立页面	搜索、读取、创建、更新、发布、回收、恢复
分类、标签	查询和管理
评论及回复	查询和管理
附件	查询、上传、删除
其他插件	发现并调用相关插件提供的MCP工具

附件上传使用Halo系统设置中的Console附件策略与分组。工具来源和最近调用记录可以在控制台查看，方便管理员核对执行情况。

二、使用前需要满足哪些条件？

安装前，先检查Halo版本、站点访问方式和客户端支持情况。

Halo版本不低于2.26.0。
生产环境使用HTTPS。
客户端支持Streamable HTTP和自定义Bearer Token认证。

本文以Codex和Claude Code为例。其他AI客户端只要满足连接要求，也可以使用对应的配置方式接入。

MCP方案省去了Halo CLI的安装步骤，但AI客户端本身仍需安装并完成必要配置。如果使用桌面客户端，还要确认它能够读取保存密钥的环境变量。

三、安装插件并创建访问密钥

1、启用MCP Server插件

进入Halo控制台，安装并启用MCP Server插件，然后打开「工具 → MCP服务」。

该管理入口仅对Halo超级管理员开放。如果没有看到入口，可以先检查当前账号权限，以及插件是否已经正常启用。

2、选择工具权限

创建访问密钥时，需要勾选允许调用的工具。

首次连接可以只开放搜索、读取等查询工具。确认站点和返回内容没有问题，再增加创建草稿、更新文章等权限。发布、删除等操作如果暂时用不到，可以不开放。

建议不同客户端使用不同密钥。这样在更换客户端或停止使用时，可以单独禁用对应密钥，不影响其他连接。

3、保存密钥与连接地址

访问密钥只会在创建或轮换后显示一次，需要及时保存。插件同时提供客户端配置，可以直接复制并按实际环境调整。

假设Halo站点地址为https://halo.example.com，MCP连接地址就是下面这样。

https://halo.example.com/mcp

后续安装的插件如果增加了MCP工具，这些工具不会自动加入已有密钥，需要管理员手动授权。

四、配置Codex或Claude Code

下面的配置均通过环境变量读取密钥，不把实际密钥写进项目文件。

1、设置环境变量

在macOS、Linux的Bash或Zsh终端中执行以下命令。

export HALO_MCP_TOKEN='替换为实际访问密钥'

Windows PowerShell使用以下写法。

$env:HALO_MCP_TOKEN = '替换为实际访问密钥'

这些命令设置的是当前终端会话的环境变量。设置完成后，从同一终端启动客户端，客户端进程才能继承该变量。已经运行的桌面应用不会自动读取新设置的值。

2、Codex配置

在Codex用户目录下的config.toml中加入以下内容。配置文件通常位于用户主目录的.codex文件夹内。

[mcp_servers.halo]
url = "https://halo.example.com/mcp"
bearer_token_env_var = "HALO_MCP_TOKEN"

将示例域名替换为实际站点域名，再重新加载客户端连接。也可以使用可信项目中的.codex/config.toml，按项目管理配置。

3、Claude Code配置

在项目根目录的.mcp.json中加入以下内容。

{
  "mcpServers": {
    "halo": {
      "type": "http",
      "url": "https://halo.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${HALO_MCP_TOKEN}"
      }
    }
  }
}

如果文件里已经配置了其他MCP服务，将halo配置合并到原有的mcpServers对象中即可，保留其他服务设置。

实际密钥不要放入JSON文件，也不要随项目提交到代码仓库。

五、连接后先做一次查询测试

完成配置后，可以先发出一个不会修改内容的请求。

列出站点中最近发布的5篇文章，显示标题和发布时间，不修改任何内容。

检查返回结果，确认连接的是目标站点，再尝试更具体的任务。

查找需要更新的文章

搜索标题中包含“安装”的文章，列出标题和发布状态，先不要修改。

整理分类和标签

查看现有标签，找出名称相近或可能重复的项目，给出合并建议，不执行合并。

创建文章草稿

创建一篇网站维护通知草稿，提醒访问者维护期间可能出现短暂无法访问的情况，暂时不要发布。

第一次使用建议按查询、草稿、更新的顺序测试。涉及现有内容修改时，先让AI列出准备修改的内容，检查后再执行。

需要注意，提示词中的“不要发布”“先确认”只能约束操作流程。要阻止客户端调用发布或删除工具，还应在密钥中关闭相应权限。

六、扩展插件可以提供哪些工具？

Halo MCP Server支持发现其他插件贡献的工具。安装相应插件并完成授权后，AI可以进一步管理文档、瞬间等内容。

插件	接入后的用途
Docsme文档管理	查询和管理文档内容
Image Stream	在Unsplash、Pixabay、Pexels搜索并转存图片
瞬间	管理瞬间内容

通过Image Stream找到的图片，使用前仍需检查授权条件，尤其是商业用途、人物肖像和商标相关限制。能够搜索或转存，不等于可以不受限制地使用。

七、连接失败时检查什么？

出现的问题	优先检查的项目
找不到MCP管理入口	Halo版本、插件启用状态、当前账号是否为超级管理员
客户端无法连接	域名、HTTPS证书、`/mcp`路径及反向代理配置
提示认证失败	密钥是否正确，是否已过期或禁用，客户端是否读取到环境变量
可以查询，但无法修改	当前密钥是否授权了对应的修改工具
新插件的工具不可用	插件是否提供MCP工具，是否已为现有密钥添加授权
浏览器直接访问报错	MCP端点需要使用支持要求的客户端连接，不能仅靠浏览器页面判断服务状态