Halo MCP Server上线附安装及配置教程

Halo站点现在可以通过MCP接入AI客户端了。安装MCP Server插件后，在后台创建访问密钥，就能让支持该连接方式的AI工具帮你搜索文章、整理分类标签、修改内容和处理评论，不用每次都打开后台逐项操作。

和CLI方案相比，这种方式省去了安装Halo CLI及配置对应Skills的步骤。MCP服务端直接运行在Halo中，本地只需配置支持Streamable HTTP和Bearer Token认证的客户端。

一、Halo MCP Server能做什么？

MCP是模型上下文协议，用于连接AI客户端与外部工具。Halo MCP Server插件将站点管理操作提供给客户端，AI便可以在授权范围内调用这些工具。

目前支持的操作包括以下几类。

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

附件上传沿用Halo系统设置中的Console附件策略与分组。管理员还可以在控制台查看工具来源及最近的调用记录，检查AI执行了哪些操作。

每个访问密钥都可以单独选择工具权限，并设置有效期、禁用状态和IP白名单，也支持密钥轮换。只需要AI查询文章时，可以仅开放查询工具，不必同时授予发布和删除权限。

二、安装前需要准备什么？

使用插件需要满足以下条件。

Halo版本为 2.26.0或更高版本。
生产环境通过HTTPS访问。
AI客户端支持Streamable HTTP，以及自定义Bearer Token认证。

Codex、Claude Code等客户端可以按下文配置。使用其他客户端时，先确认其支持上述连接和认证方式。

这里不需要额外安装Halo CLI。不过，所选AI客户端自身的安装、登录和运行环境仍需准备好。

三、在Halo后台启用MCP服务

先在Halo控制台安装并启用MCP Server插件，再进入「工具 → MCP服务」，创建访问密钥。

创建时，勾选这个密钥可以调用的工具。第一次连接建议只开放搜索、读取等操作，确认能正常访问后，再按需要增加内容修改或发布权限。

插件提供的MCP端点格式如下，将示例域名替换为自己的站点域名即可。

https://halo.example.com/mcp

访问密钥仅在创建或轮换后显示一次，需要及时保存。 MCP服务管理入口仅向Halo超级管理员开放，后续新安装的工具也不会自动加入已有密钥，需要管理员手动授权。

四、连接AI客户端

以下示例使用环境变量保存密钥，避免直接把密钥写进项目配置文件。

在macOS、Linux或其他支持此语法的Shell中执行以下命令，将占位内容替换为实际密钥。

export HALO_MCP_TOKEN='hmcp_replace_me'

随后从同一终端启动客户端，使其能够读取这个环境变量。若使用桌面客户端，需要通过对应的启动环境或安全配置方式传入密钥。

1、Codex配置

将以下内容加入用户级配置文件~/.codex/config.toml，也可以放在可信项目的.codex/config.toml中。

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

保存后，重新加载客户端的MCP连接。域名需要替换为实际Halo站点地址，环境变量名称则应与前面设置的一致。

2、Claude Code配置

在项目级.mcp.json中加入以下配置，通过环境变量读取访问密钥。

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

如果文件中已有其他MCP服务，只需将halo这一项合并到现有的mcpServers对象中，不要覆盖原配置。

五、连接后可以怎么用？

第一次使用，可以先让AI执行查询，确认连接的是正确站点、返回的内容也符合预期。

例如，可以直接提出这些要求。

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

查看现有分类和标签，找出可能重复的名称，先给出整理建议，不执行修改。

创建一篇介绍网站更新的草稿，完成后供我检查，暂时不要发布。

确认查询、创建草稿等操作正常后，再逐步使用更新文章、管理评论等功能。AI能否执行某项操作，取决于对应密钥是否获得了该工具权限。

对于发布、删除、回收等操作，建议先查看处理清单，再确认执行。提示词中的“先确认”可以帮助约束操作流程，真正的访问范围仍应通过密钥权限控制。

六、哪些插件已经接入？

除Halo本身的内容管理功能外，其他插件也可以提供MCP工具。目前列出的接入插件包括以下三款。

插件	可用场景
Docsme文档管理	让AI管理文档内容
Image Stream	在Unsplash、Pixabay、Pexels搜索并转存图片
瞬间	让AI管理瞬间内容

图片能否用于具体项目，需要查看对应平台及图片的授权条件，不能将图库图片一概视为没有版权限制。

安装相关插件后，还需检查新增工具，并为需要使用它们的访问密钥添加权限。

七、使用时注意密钥和访问权限

建议为不同客户端分别创建密钥，只开放实际需要的工具。密钥不要提交到代码仓库，也不要放进公开截图或日志中；不再使用的客户端，应及时禁用对应密钥。

IP白名单可以作为额外防护，但不能替代HTTPS和工具授权。

如果Halo部署在反向代理后面，应仅信任可信代理写入的Forwarded及X-Forwarded-*请求头，并限制外部请求绕过代理直接访问Halo。

插件默认不允许带有Origin请求头的浏览器直连请求，连接时应使用支持要求的MCP客户端或调试工具。

八、MCP和CLI方案怎么选？

对比项	MCP方案	CLI配合Skills方案
操作入口	AI客户端调用Halo提供的工具	通过命令行执行操作
环境准备	Halo安装插件，客户端配置端点和密钥	本地安装CLI及所需运行环境，配置对应Skills
权限管理	按访问密钥选择可用工具	取决于CLI及账号的授权机制
适合场景	在对话中查询、编辑和管理站点内容	已有终端工作流，需要结合脚本处理任务