Halo MCP 部署指南:让 Codex 直接读写你的博客
以前管理 Halo 博客,要么打开后台慢慢点,要么写脚本调 REST API。现在有了 MCP(Model Context Protocol),事情变得简单了:只要给 Halo 装上 MCP 插件、生成一个访问令牌,再把端点配置进 Codex、Claude Code、MCP Inspector 等任意 MCP 客户端,AI 就能直接读文章、写文章、管理评论和附件。
💡 本文就是走这条链路发布的——封面由 HTML/CSS 排版渲染,经halo_upload_attachment上传,再经halo_create_post创建并发布,全程没有打开后台编辑器。
一、准备工作
- 一个可正常访问的 Halo 2.x 站点(示例域名:
https://idindoo.com); - 具备管理员权限的账号;
- 一台装有 Codex Desktop / CLI 的电脑(其他 MCP 客户端同理)。
二、安装 MCP 插件
Halo 官方提供了 MCP Server 插件:halo-dev/plugin-mcp-server。在 Halo 后台进入「插件」→「插件市场」,搜索并安装即可;也可以按官方仓库说明下载插件包后手动上传安装。
安装完成后,插件会在你的站点上暴露一个 MCP 端点,默认路径为:
https://你的域名/mcp三、创建访问令牌
MCP 插件使用 Halo 的「个人访问令牌(PAT)」做鉴权。在 Halo 后台进入「个人资料 / 安全设置」,创建一个新的访问令牌,复制生成的密钥。令牌通常以 hmcp_ 开头,形如:
hmcp_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxx⚠️ 安全提醒:请把令牌当作密码保管。它拥有与你的账号同等的权限,不要把它提交到代码仓库、写进文章或发送给任何人。
四、在 Codex 中配置
编辑 Codex 的全局配置文件 ~/.codex/config.toml,追加以下内容:
# ~/.codex/config.toml
[mcp_servers.halo]
url = "https://你的域名/mcp"
enabled = true
[mcp_servers.halo.http_headers]
Authorization = "Bearer hmcp_你的访问令牌"官方 README 推荐的写法是通过环境变量注入令牌,适合多台机器复用同一份配置、避免令牌直接写进配置文件:
# ~/.codex/config.toml
[mcp_servers.halo]
url = "https://你的域名/mcp"
bearer_token_env_var = "HALO_MCP_TOKEN"# shell 中导出环境变量
export HALO_MCP_TOKEN="hmcp_你的访问令牌"保存后重启 Codex(或重载会话),halo_* 工具就会注入到当前对话中。
五、验证联通
配置完成后,先在 Codex 里直接说一句:「用 halo 工具列出最近的文章」。如果一切正常,它会调用 halo_list_posts 并返回文章列表。
想手动确认链路,也可以直接 curl 走一遍 MCP 协议,一共三步:
- 发送
initialize握手,拿到 200; - 发送
notifications/initialized; - 调用
tools/list查看工具列表。
curl -X POST https://你的域名/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":"curl-test","version":"1.0.0"}
}
}'curl -X POST https://你的域名/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。插件、令牌、客户端三层全部联通。
六、能力一览
插件提供的 24 个工具覆盖了博客日常管理的方方面面,大致分为五组:
| 分组 | 代表工具 | 用途 |
|---|---|---|
| 文章 | halo_list_postshalo_create_posthalo_update_posthalo_set_post_publish_state | 列出、创建、更新、发布/撤回文章 |
| 页面 | halo_list_single_pageshalo_create_single_page | 管理独立页面(关于、友链等) |
| 分类与标签 | halo_list_categorieshalo_create_taghalo_update_category | 维护文章组织结构 |
| 评论 | halo_list_commentshalo_set_comment_approval | 审核、管理评论与回复 |
| 附件 | halo_upload_attachmenthalo_get_attachment | 上传图片、读取附件信息 |
再加上全文检索 halo_search_content,几乎可以把「后台管理」这件事整体交给 AI 完成。
七、安全建议
- 令牌即账号:只配置在受信任的客户端上,泄露后第一时间到后台吊销并重新生成;
- 优先使用环境变量注入令牌,避免密钥散落在配置文件里;
- 务必通过 HTTPS 访问 MCP 端点,防止令牌在传输中被截获;
- 不要把令牌写进文章、笔记、公开仓库或截图。
八、结语
从「装插件」到「Codex 直接调工具」,整个过程十分钟以内。以后写文章、批量改分类、审核评论,都可以直接对 AI 说一句话完成。本文从封面设计到正文发布,全程没有打开后台编辑器——这就是 MCP 给个人站点带来的新体验。
关联资源:halo-dev/plugin-mcp-server · Codex 官方文档 · MCP 规范
