一、准备工作

• 一个可正常访问的 Halo 2.x 站点(示例域名:https://idindoo.com);
• 具备管理员权限的账号;
• 一台装有 MiniMax code 或 Codex Desktop / CLI / Claude Code 的电脑(其他 MCP 客户端同理)。

⚠️ 前置条件:Halo 版本需 ≥ 2.26.0,站点必须 HTTPS。MCP 协议默认拒绝明文 HTTP,生产环境必须上 Cloudflare 或 Caddy。

二、安装 Halo MCP 插件

Halo 官方提供了 MCP Server 插件 halo-dev/plugin-mcp-server。在 Halo 后台进入「插件」→「插件市场」,搜索并安装即可;也可以按官方仓库说明下载插件包后手动上传安装。

安装完成后,插件会在你的站点上暴露一个 MCP 端点,默认路径为:

https://你的域名/mcp

三、创建访问令牌

Halo MCP 插件使用 Halo 的「个人访问令牌(PAT)」做鉴权。在 Halo 后台进入「个人资料 / 安全设置」,创建一个新的访问令牌,复制生成的密钥。令牌通常以 hmcp_ 开头,形如:

hmcp_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxx

⚠️ 安全提醒:请把令牌当作密码保管。它拥有与你的账号同等的权限,不要把它提交到代码仓库、写进文章或发送给任何人。

四、在 MiniMax code 中配置

我用的客户端是 MiniMax code(也支持 Codex / Claude Code / Inspector,思路一样,任何支持 MCP HTTP transport 的客户端都行)。Halo MCP server 走 Streamable HTTP + Bearer Token,配置一行搞定:

mavis mcp create \
  --name halo-mcp \
  --transport http \
  --url https://idindoo.com/mcp \
  --header "Authorization=Bearer hmcp_你的密钥" \
  --timeout 30000 \
  --enabled true

💡 命令说明:上面 mavis mcp create 是 Mavis(我的桌面 agent)使用的命令,任何支持 MCP 的客户端配置思路都一样——URL + Bearer Token 两件事。如果你用 MiniMax code / Codex,配置文件里把 url 和 bearer_token 填上即可。

跑完 mavis mcp get halo-mcp 验证一下:

{
  "name": "halo-mcp",
  "enabled": true,
  "config": {
    "transport": "http",
    "endpoint": "https://idindoo.com/mcp",
    "headerKeys": ["Authorization"],
    "timeoutMs": 30000
  }
}

✅ 安全细节:headerKeys 只回显键名,token 不会出现在任何 tool result 里。mcp config 内部加密存储,比写进 toml 安全多了。

如果你用 Codex,官方 README 推荐的写法是通过环境变量注入令牌,适合多台机器复用同一份配置、避免令牌直接写进配置文件:

# ~/.codex/config.toml
[mcp_servers.halo]
url = "https://idindoo.com/mcp"
bearer_token_env_var = "HALO_MCP_TOKEN"

# shell 中导出环境变量
export HALO_MCP_TOKEN="hmcp_你的访问令牌"

保存后重启 Codex(或重载会话),halo_* 工具就会注入到当前对话中。

五、验证 MiniMax code × Halo MCP 联通

配置完成后,先在 MiniMax code 里直接说一句:「用 halo 工具列出最近的文章」。如果一切正常,它会调用 halo_list_posts 并返回文章列表。

想手动确认链路,也可以直接 curl 走一遍 MCP 协议,一共三步:

1. 发送 initialize 握手,拿到 200;
2. 发送 notifications/initialized;
3. 调用 tools/list 查看工具列表。

curl -X POST https://idindoo.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer hmcp_你的访问令牌" \
  -d '{
    "jsonrpc":"2.0","id":1,"method":"initialize",
    "params":{
      "protocolVersion":"2025-03-26",
      "capabilities":{},
      "clientInfo":{"name":"minimax-code","version":"0.0.1"}
    }
  }'

返回里有 serverInfo:

{
  "protocolVersion": "2025-03-26",
  "serverInfo": {
    "name": "halo-mcp-server",
    "version": "1.0.0-beta.1"
  }
}

再调 tools/list:

curl -X POST https://idindoo.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer hmcp_你的访问令牌" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

返回示例:

{
  "jsonrpc":"2.0",
  "id":2,
  "result":{
    "tools":[
      {"name":"halo_list_posts",...},
      {"name":"halo_create_post",...}
    ]
  }
}

✅ 本次实测结果:握手 200 → initialized 202 → tools/list 返回 24 个 halo_* 工具;不带令牌的请求返回 401。Halo MCP × MiniMax code 联通成功。

踩了一个 token 坑

第一次配的时候,我直接把完整 token 塞进了 bearer_token 字段(或写进 bearer_token_env_var 当变量值)。MiniMax code / Codex 启动时去查环境变量查不到,MCP 连不上,debug 半天才反应过来:

💡 bearer_token_env_var 是「环境变量名」("HALO_MCP_TOKEN"),不是 token 本身。

血泪教训:以后看到 bearer_token_env_var 先想 5 秒——这是名字还是值?

token 轮换,旧的真死了

前面我在 chat 里把完整 token 发出来过——虽然 Mavis 的 mcp create 是 write-only 不会回显,但 chat 历史里那个 token 等于公开了。稳妥起见,去 Halo 后台「工具 → MCP 服务」点「轮换」,新密钥生成,旧密钥立即失效。

轮换后做了 4 步验证:

• mavis mcp update halo-mcp 把 Authorization 头换成新值
• mavis mcp get halo-mcp 确认 headerKeys 仍是 ["Authorization"]
• 带新 token 跑 initialize → tools/list,24 工具全在
• 用旧 token 打一次,拿到 HTTP 401——证明旧 token 真死了

六、能力一览

Halo MCP 插件提供的 24 个工具覆盖了博客日常管理的方方面面,大致分为五组:

再加上全文检索 halo_search_content,几乎可以把「后台管理」这件事整体交给 MiniMax code 完成。

七、安全建议

• 令牌即账号:只配置在受信任的客户端上,泄露后第一时间到 Halo 后台吊销并重新生成;
• 优先使用环境变量注入令牌,避免密钥散落在配置文件里;
• 务必通过 HTTPS 访问 Halo MCP 端点,防止令牌在传输中被截获;
• 不要把令牌写进文章、笔记、公开仓库或截图。

⚠️ Cloudflare WAF 经验:Cloudflare 反代后面跑 Halo,通过 MCP/HTTP 提交大 body 写/更新内容时,WAF 可能拦下带 <style> 块 + linear-gradient + !important 的 HTML;实测 8KB markdown body 200 OK,但 6KB 纯 HTML 被 403。优先用 markdown 提交,别瞎试 5/10/20KB 调阈值。

八、结语

从「装 Halo MCP 插件」到「MiniMax code 直接调工具」,整个过程五分钟以内。Halo MCP 暴露 24 个工具,任何支持 MCP 的客户端(MiniMax code / Codex / Claude Code / Inspector)都能联通——配置思路都一样:URL + Bearer Token 两件事。

以后写文章、批量改分类、审核评论,都可以直接对 AI 说一句话完成。本文从封面设计到正文发布,全程没有打开 Halo 后台编辑器——这就是 Halo MCP × MiniMax code 联通给个人站点带来的新体验。

关联资源:halo-dev/plugin-mcp-server · MCP 规范 · MiniMax code 官方文档

💡 本文就是走这条链路发布的——封面由 HTML/CSS 排版渲染,经 halo_upload_attachment 上传,再经 halo_create_post 创建并发布,全程 Halo MCP × MiniMax code 联通,没打开后台编辑器。