Halo 博客 MCP 接入与连接测试（Cursor）

让 AI 通过 MCP 管理 Halo 博客：创建、编辑、发布文章等。文档更新：2026-05-29 项目地址：https://github.com/Huangwh826/halo-mcp-server

一、方案说明

用户 / AI 对话 → Cursor Agent → halo-mcp-server → Halo REST API → Halo 博客

MCP Server：halo-mcp-server（Python，PyPI 包）
支持客户端：Cursor、Claude Desktop 等
核心能力：30+ 工具（文章/分类/标签/附件）+ 10 个 AI 写作 Prompt

二、前置条件

项目	要求
Halo 版本	≥ 2.21
Python	≥ 3.10（macOS 系统自带 3.9 不够用）
Halo Token	个人中心 → 个人令牌，生成 `pat_` 开头令牌
权限	建议勾选内容管理相关权限

获取 Halo 个人令牌

登录 Halo 后台 → 左下角 个人中心（或访问 /uc）
进入 个人令牌 → 生成新令牌
设置名称（如 MCP Server），勾选内容管理权限
复制 pat_ 开头的令牌（仅显示一次）

官方文档：https://docs.halo.run/developer-guide/restful-api/introduction

三、安装 halo-mcp-server

macOS 若系统 python3 为 3.9，需用 Anaconda 3.12：

# 查看可用 Python
which python3
python3.12 --version

# 安装（推荐用 3.10+）
python3.12 -m pip install halo-mcp-server

# 验证模块可导入
python3.12 -c "import halo_mcp_server; print('ok')"

四、Cursor 配置

配置文件：~/.cursor/mcp.json（全局）或项目级 .cursor/mcp.json

在 mcpServers 中追加：

"halo": {
  "command": "python3.12",
  "args": ["-m", "halo_mcp_server"],
  "env": {
    "HALO_BASE_URL": "https://your-halo-site.com",
    "HALO_TOKEN": "${env:HALO_TOKEN}"
  }
}

注意：

command 必须指向 Python 3.10+ 解释器

Token 建议改用环境变量 "HALO_TOKEN": "${env:HALO_TOKEN}"，避免明文写入配置文件

配置后需 完全退出并重启 Cursor

五、连接测试方法

方法 1：Cursor MCP 面板检查

打开 Settings → Tools & MCP
找到 halo 服务，确认状态为 已连接（绿点）
若报错，查看错误日志（常见：Python 版本过低、包未安装、Token 无效）

方法 2：自然语言测试（推荐）

在 Cursor 对话中输入：

列出我的所有博客文章

或：

列出我最新的 10 篇博客文章

成功标志：AI 返回文章列表（标题、发布日期、链接等），无报错。

方法 3：REST API 直连测试（绕过 MCP）

当 MCP 服务异常时，可用 curl 验证 Token 和博客 API 是否正常：

# 设置变量（替换为你的 Token）
export HALO_BASE_URL="https://your-halo-site.com"
export HALO_TOKEN="$HALO_TOKEN"  # 先在 shell 中设置

# 列出最新 10 篇文章
curl -s \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Accept: application/json" \
  "$HALO_BASE_URL/apis/content.halo.run/v1alpha1/posts?page=1&size=10&sort=spec.publishTime,desc" \
  | python3 -m json.tool

成功标志：返回 JSON，total 为文章总数，items 包含文章列表。

方法 4：验证 Python 模块启动

python3.12 -m halo_mcp_server

MCP 服务以 stdio 模式运行，启动后等待输入属正常（Ctrl+C 退出）。若报 ModuleNotFoundError，说明包未安装到该 Python 环境。

六、AI 发文章示例

配置成功后，可直接用自然语言：

帮我写一篇关于 Python 异步编程的技术文章，打上 Python、asyncio 标签，并发布

AI 会自动调用：

halo_blog_writing_assistant — 生成正文
list_categories / list_tags — 查分类标签
create_post — 创建 Markdown 文章
publish_post — 发布

常用 MCP 工具

工具	功能	示例指令
`list_my_posts`	列出文章	"列出我的所有文章"
`create_post`	创建文章	"创建一篇草稿"
`publish_post`	发布文章	"发布这篇文章"
`update_post`	更新文章	"修改文章标题"
`list_categories`	列出分类	"列出所有分类"
`list_tags`	列出标签	"列出所有标签"