ghost-mcp-server

Ghost MCP 服务：通过 Claude、Cursor 和其他 AI 客户端管理 Ghost CMS

Ghost MCP Server 是一个使用 TypeScript 编写的 Ghost CMS 开源 Model Context Protocol 服务。它通过 stdio 将 Claude Desktop、Claude Code 或 Cursor 等 MCP 客户端连接到 Ghost Admin API。借助它，AI 助手可以创建和编辑文章与页面、设置 SEO 元数据、管理标签、会员和新闻简报、上传图片和主题，以及导出内容。

它提供 60 个工具：55 个专用 API 工具、3 个用于 SEO 和标签的快捷工具、一个路由搜索工具和一个通用请求工具。内置目录涵盖来自固定版本 Ghost 源代码快照的 253 个 Admin API 路由。具体哪些功能可在你的网站上使用，取决于你的凭据、Ghost 版本和功能标志。路由和来源列于 GHOST_API.list。

快速开始

你需要 Node.js 20 或更高版本，以及一个可访问 Admin API 的 Ghost 站点。

1. 在 Ghost Admin 中，打开 Settings → Integrations → Add custom integration，并复制 Admin API Key（id:secret）。请勿使用 Content API 密钥。
2. 将服务添加到客户端配置中。对于 Claude Desktop 或 Cursor：

{
  "mcpServers": {
    "ghost": {
      "command": "npx",
      "args": ["-y", "@proars/ghost-mcp-server"],
      "env": {
        "GHOST_API_URL": "https://your-blog.com",
        "GHOST_ADMIN_API_KEY": "64f1a2b3c4d5e6f7a8b9c0d1:3e5f7a9b1c2d4e6f8a0b2c4d6e8f0a1b3c5d7e9f1a2b4c6d8e0f2a3b5c7d9e1f"
      }
    }
  }
}

上面的密钥是按真实格式编造的示例：24 个十六进制字符、一个冒号，然后是 64 个十六进制字符。请将两个值都替换为你自己的值。

使用 npx 运行服务时，请按如下所示通过 env 传递设置。只有从源代码检出目录运行时才会读取 .env 文件（见下文），或者从 GHOST_MCP_ENV_FILE 指定的路径读取。

3. 重启客户端，并提出类似“列出我最近发布的文章及其 SEO 标题”的请求。

GHOST_API_URL 是规范的 Admin 域名，包含任何站点子目录，但不包含 /ghost/api/admin。对于本地站点，请使用类似 http://localhost:2368 的地址。

配置文件位置：macOS 上的 Claude Desktop 使用 ~/Library/Application Support/Claude/claude_desktop_config.json。Cursor 使用 ~/.cursor/mcp.json，或项目中的 .cursor/mcp.json。

Claude Code：

claude mcp add ghost --scope user \
  -e GHOST_API_URL=https://your-blog.com \
  -e GHOST_ADMIN_API_KEY=64f1a2b3c4d5e6f7a8b9c0d1:3e5f7a9b1c2d4e6f8a0b2c4d6e8f0a1b3c5d7e9f1a2b4c6d8e0f2a3b5c7d9e1f \
  -- npx -y @proars/ghost-mcp-server

--scope user 会使服务在每个文件夹中都可用。不使用该选项时，服务只会在你运行命令的文件夹中注册。Claude Code 会自行启动和停止服务，因此你无需保持终端打开。

运行 claude mcp get ghost 检查连接状态，该命令应报告 Connected；也可以在 claude 会话中输入 /mcp。要移除服务，请运行 claude mcp remove ghost -s user。

任何其他 stdio MCP 客户端都可以运行相同的命令 npx -y @proars/ghost-mcp-server，并提供这两个环境变量。

更新： npx 使用缓存，因此每次启动时都不一定会通过 @latest 检查注册表。若要在每次运行命令时强制检查注册表中的最新版本，请使用 npx --prefer-online -y @proars/ghost-mcp-server@latest。在 JSON 客户端配置中，将 args 设置为：

["--prefer-online", "-y", "@proars/ghost-mcp-server@latest"]

若要固定使用某个版本，请指定版本号，例如 @proars/[email protected]。有关各版本的变更，请参阅更新日志。

请勿在本仓库的克隆目录中运行 npx：npm 会找到名称相同的本地 package.json，并报错 ghost-mcp-server: command not found。请在其他任意文件夹中运行。

从源代码安装

如果你想修改代码或运行尚未发布的版本，请使用此方式。

git clone https://github.com/proars/ghost-mcp-server.git
cd ghost-mcp-server
npm install
npm run build
cp .env.example .env

在 .env 中填写 GHOST_API_URL 和 GHOST_ADMIN_API_KEY，然后让客户端指向构建产物。请保留 --silent：否则 npm 的启动横幅会输出到 stdout，进入 MCP 协议流。

{
  "mcpServers": {
    "ghost": {
      "command": "npm",
      "args": ["--silent", "--prefix", "/ABSOLUTE/PATH/ghost-mcp-server", "start"]
    }
  }
}

无论客户端从哪个目录启动服务，都会读取项目根目录中的 .env 文件。已设置的变量优先级更高；如果两个必需变量都已设置，则完全不会读取该文件。GHOST_MCP_ENV_FILE 用于指定其他 env 文件，GHOST_MCP_SKIP_DOTENV=1 则会关闭文件加载。

服务能做什么？

资源	工具
文章	get_posts、get_post、get_post_by_slug、create_post、update_post、delete_post、copy_post
页面	get_pages、get_page、get_page_by_slug、create_page、update_page、delete_page、copy_page
标签	get_tags、get_tag、get_tag_by_slug、create_tag、update_tag、delete_tag
会员等级	get_tiers、get_tier、create_tier、update_tier
新闻简报	get_newsletters、get_newsletter、create_newsletter、update_newsletter
优惠	get_offers、get_offer、create_offer、update_offer
会员	get_members、get_member、create_member、update_member、delete_member
标签	get_labels、create_label、update_label、delete_label
员工	get_users、get_user、update_user、delete_user、get_roles、invite_user
图片和主题	upload_image、upload_theme、activate_theme
Webhook	create_webhook、update_webhook、delete_webhook
站点	get_site、get_settings
快捷操作	update_post_seo、update_page_seo、update_post_tags
发现与通用调用	ghost_list_endpoints、ghost_api_request

Ghost 没有用于删除会员等级、新闻简报或优惠的端点，因此这些资源没有 delete_* 工具。

警告：此服务会公开所有受支持的功能，包括具有破坏性的功能。 delete_post、delete_page、delete_tag、delete_member、delete_user、activate_theme、upload_theme 和 ghost_api_request 可能会永久删除或覆盖内容、订阅者和站点设置。已删除的记录通常无法恢复。请为此服务创建单独的集成密钥，在进行批量操作前从 Ghost Admin 导出内容备份，并在客户端中对所有 update_*、delete_* 和通用调用启用手动审批。

如何调用这些工具？

• 创建和更新： 将记录字段放入 data，并将记录的 id 作为单独参数传入。更新文章和页面时，需要使用最新读取结果中的 data.updated_at。SEO 快捷操作（update_post_seo、update_page_seo）和标签快捷操作则直接接收 updated_at。
• 列表： 使用 limit、page、filter、order、include 和 fields。默认情况下，文章和页面会返回包含标签的精简字段。读取单条记录时会返回完整记录。
• SEO： update_post_seo 和 update_page_seo 可在一次调用中设置 meta_title、meta_description、og_title 和 og_description。传入 id、当前的 updated_at，以及这些字段中的至少一个。未传入的字段保持不变。
• 标签： 设置标签会替换整个标签集合。尚不存在的标签会被创建，传入空数组则会移除所有标签。
• 发布： 调用 update_post 并设置 data.status="published"，或设置为 "scheduled" 并将 data.published_at 设为未来时间。若要通过电子邮件发送文章，请添加 newsletter（一个 slug），并可选添加 email_segment。
• 图片： upload_image 接收 file_path、可选的 purpose（image、profile_image 或 icon）以及 ref。

如何访问没有专用工具的路由？

使用 ghost_list_endpoints 按 group、method、access 或 search 搜索。设置 without_dedicated_tool=true，即可列出其他 198 个路由。每个条目都会显示访问要求、功能标志和上传字段。

使用 ghost_api_request 调用任意路由。其 path 相对于 /ghost/api/admin，包含真实 ID 或 slug，且不含查询字符串。

ghost_api_request method=GET  path=/labels/slug/vip/
ghost_api_request method=POST path=/members/upload/ files={membersfile: "/Users/me/members.csv"}
ghost_api_request method=GET  path=/posts/export/   save_to="/Users/me/posts.csv"

在 body 中发送 JSON 载荷，使用 Ghost 期望的结构。将查询参数放入 query。以 files={formField: "/absolute/path"} 的形式发送 multipart 文件，并可选择提供文本 fields。

对于下载，save_to 必须指定现有且可写文件夹中的新文件。末尾带分隔符的路径会被拒绝，且绝不会覆盖已有文件。如果 POST、PUT 或 DELETE 返回文件，请在首次调用时设置 save_to，因为为获取响应而重复执行变更操作，可能会再次产生效果。

它需要哪些 Ghost 权限？

类别	路由	要求
I / PUBLIC	125	集成密钥允许列表或公开访问。处理程序权限仍然适用。
U	116	具有所需角色的员工用户访问令牌，或用户会话。
SESSION	3	用户 Cookie 会话。集成密钥和员工令牌均会被阻止。
FLOW	9	具有各自身份验证机制的登录、恢复和设置流程。

若要使用员工令牌，请将用户 Ghost Admin 个人资料中的令牌填入 GHOST_ADMIN_API_KEY。其权限取决于用户角色。员工令牌不能调用 DELETE /db/、PUT /users/owner/ 或 POST /authentication/reset/。

此服务不实现 Cookie 会话、登录或 2FA。这些路由仅列在目录中供发现。

请求会发送 Accept-Version: v5.0。该目录是 Ghost main 分支的快照，因此包含较新或实验性路由，这些路由在你的安装版本上可能会返回 404。目录不包含公开 Content API。

允许 AI 客户端访问我的站点安全吗？

请将其视同任何拥有博客写入权限的账户，并确保有人工参与。

• 将密钥保存在客户端环境中或 .env 文件里，切勿提交。对破坏性工具启用手动审批：所有 update_* 和 delete_* 工具、activate_theme、upload_theme 以及 ghost_api_request。
• 如果变更请求发送后失败，请先检查 Ghost，再重试，因为请求可能已经生效。若响应被截断，请使用读取工具检查结果。
• 永远不会跟随重定向。请配置规范 Admin URL；如果变更操作收到重定向，请在发送其他请求前检查结果。
• 本地文件路径必须是绝对路径。隐藏路径组件无论按原样还是经过符号链接解析，都会被拒绝。上传必须使用常规文件；下载文件会在请求前预留，并设置仅所有者可访问的权限。
• 文件检查并非沙箱。它们无法保护名称可见的敏感文件，也无法阻止本地进程在调用期间改写目录。请将站点内容视为不可信内容，并审核上传请求。
• 上传和下载都会缓冲在内存中。HTTP 请求在 120 秒后超时，超过 100,000 个字符的工具响应会被截断。

开发

npm run typecheck   # tsc --noEmit
npm test            # regression tests with synthetic credentials and a local fake Ghost server
npm run catalog     # regenerate src/catalog.ts from GHOST_API.list
npm run build       # compile to dist/
npm start           # run the build over stdio (requires configuration)

路由列表位于 GHOST_API.list。scripts/generate-catalog.mjs 会将其转换为 src/catalog.ts，切勿手动编辑该文件。若要更改路由，请编辑列表，运行 npm run catalog，然后运行测试。日志会写入 stderr，因为 stdout 专用于 MCP 消息。

对于每次推送到 main 的操作以及每个拉取请求，GitHub Actions 都会在 Node 20 和 22 上运行类型检查、构建和测试。

测试会检查目录与工具的一致性、请求构建、文件安全、重定向、重试指引和配置隔离。但这些测试无法证明其与正在运行的 Ghost 实例兼容。

常见问题

它能与自托管的 Ghost 和 Ghost(Pro) 配合使用吗？ 可以，只要你能访问 Admin API 并拥有密钥即可。将 GHOST_API_URL 设置为 Ghost Admin 中自定义集成页面显示的 API URL。这对 Ghost(Pro) 和使用自定义域名的网站尤为重要，因为服务端不会跟随重定向：如果某个地址会重定向到另一个地址，就会失败。

它支持哪些客户端？ 任何能够启动 stdio 服务的 MCP 客户端都可以，包括 Claude Desktop、Claude Code 和 Cursor。

不使用 Admin 密钥，它能读取我的公开内容吗？ 不能。它只使用 Admin API，不支持公开的 Content API。

它能删除我的内容吗？ 可以，delete_post、delete_page 等工具执行的删除操作无法撤销。请在客户端中为这些操作启用手动批准。

许可证

MIT。