使用说明

Ghost MCP服务器

这个项目(ghost-mcp-server)实施a 模型上下文协议（MCP）服务器 它允许MCP客户端（如Cursor或Claude Desktop）通过定义的工具与Ghost CMS实例进行交互。

需求

Node.js 18.0.0或更高版本
Ghost管理员API URL和密钥

Ghost MCP服务器详细信息

该服务器将Ghost CMS管理功能作为MCP工具公开，允许像Cursor或Claude Desktop这样的AI客户端管理Ghost博客。

MCP客户端可以通过在其根端点查询正在运行的MCP服务器（默认情况下通常在端口3001上监听）来发现这些资源和工具（例如。， http://localhost:3001/).服务器根据模型上下文协议规范以其能力进行响应。

资源定义

ghost/tag：表示Ghost CMS中的标记。包含 id, name, slug, description.
ghost/post：表示Ghost CMS中的帖子。包含 id, title, slug, html, status, feature_image, published_at, tags，元数据字段。
ghost/page：表示Ghost CMS中的页面。类似于帖子，但没有标签支持。
ghost/member：表示Ghost CMS中的成员/订阅者。包含 id, email, name, status, labels，订阅。
ghost/newsletter：代表Ghost CMS中的时事通讯。包含 id, name, description，发件人设置。
ghost/tier：表示Ghost CMS中的成员层。包含 id, name, description、定价、福利。

（参见 src/mcp_server.js 对于完整的资源模式。)

工具定义

Ghost MCP服务器提供 34工具 跨越7种资源类型。以下是一份全面的指南：

标记工具（5个工具）

ghost_create_tag -创建新标记。
- name （string，必填）：新标记的名称。
- description （string，可选）：标记的描述。
- slug （字符串，可选）：一个URL友好的slug（如果省略则自动生成）。
ghost_get_tags -使用可选筛选检索标记列表。
- name （字符串，可选）：按确切名称过滤标签。
- limit, page, order （可选）：分页和排序选项。
ghost_get_tag -通过ID或slug检索单个标记。
- id （string，可选）：标记的ID。
- slug （string，可选）：标签的slug。
- include （string，可选）：要包含的其他资源（例如，“count.posts”）。
ghost_update_tag -更新现有标记。
- id （string，必填）：要更新的标记的ID。
- name, description, slug （可选）：要更新的字段。
ghost_delete_tag -永久删除标记。
- id （string，必填）：要删除的标记的ID。

图像工具（1个工具）

ghost_upload_image -下载、处理图像并将其上传到Ghost。
- imageUrl （string，必填）：图像的可公开访问的URL。
- alt （字符串，可选）：Alt文本（如果省略则自动生成）。
- 退货: { url, alt } -Ghost URL和alt文本。
- 使用说明：在创建帖子/页面之前，先调用此函数以获取Ghost图像URL。

帖子工具（6个工具）

ghost_create_post -创建新帖子。
- title （string，必填）：帖子的标题。
- html （string，必填）：HTML格式的主要内容。
- status （字符串，可选）：“草稿”、“已发布”或“已安排”。
- tags （数组，可选）：标记名称（如果缺少，则自动创建）。
- published_at （ISO日期，可选）：如果状态为“已安排”，则为必填项。
- feature_image, feature_image_alt, feature_image_caption （可选）：特色图像设置。
- custom_excerpt, meta_title, meta_description （可选）：SEO字段。
ghost_get_posts -通过分页和筛选检索帖子。
- status （可选）：按“已发布”、“草稿”、“计划”或“全部”筛选。
- limit, page, filter, order, include （可选）：查询选项。
ghost_get_post -通过ID或slug检索单个帖子。
- id （string，可选）：帖子的ID。
- slug （string，可选）：柱子的塞子。
- include （字符串，可选）：要包含的关系（例如，“标签、作者”）。
ghost_search_posts -按标题/内容搜索帖子。
- query （字符串，必填）：搜索查询。
- status （可选）：按状态筛选。
- limit （可选）：最大结果（1-50）。
ghost_update_post -更新现有帖子。
- id （string，必填）：要更新的帖子的ID。
- 所有其他帖子字段都是可选的。
ghost_delete_post -永久删除帖子。
- id （string，必填）：要删除的帖子的ID。

页面工具（6个工具）

ghost_create_page -创建新页面（页面不支持标签）。
- title （string，必填）：页面的标题。
- html （string，必填）：HTML格式的主要内容。
- status, published_at, feature_image，SEO字段（可选）。
ghost_get_pages -使用分页和筛选检索页面。
- limit, page, filter, order, include （可选）：查询选项。
ghost_get_page -按ID或slug检索单个页面。
- id （字符串，可选）：页面的ID。
- slug （string，可选）：页面的slug。
ghost_search_pages -按标题/内容搜索页面。
- query （字符串，必填）：搜索查询。
- status, limit （可选）：过滤选项。
ghost_update_page -更新现有页面。
- id （string，必填）：要更新的页面的ID。
ghost_delete_page -永久删除页面。
- id （string，必填）：要删除的页面的ID。

成员工具（6个工具）

ghost_create_member -创建新成员/订阅者。
- email （string，必填）：成员的电子邮件地址。
- name （string，可选）：成员的名称。
- note （string，可选）：关于成员的内部注释。
- labels （数组，可选）：要分配的标签。
- newsletters （数组，可选）：要订阅的时事通讯ID。
ghost_get_members -使用分页和筛选检索成员。
- limit, page, filter, order, include （可选）：查询选项。
ghost_get_member -通过ID或电子邮件检索单个成员。
- id （string，可选）：成员的ID。
- email （string，可选）：成员的电子邮件。
ghost_search_members -按姓名或电子邮件搜索成员。
- query （字符串，必填）：搜索查询。
- limit （可选）：最大结果（1-50）。
ghost_update_member -更新现有成员。
- id （string，必填）：要更新的成员的ID。
- email, name, note, labels, newsletters （可选）。
ghost_delete_member -永久删除成员。
- id （string，必填）：要删除的成员的ID。

通讯工具（5个工具）

ghost_create_newsletter -创建新的时事通讯。
- name （string，必填）：时事通讯名称。
- description （字符串，可选）：通讯描述。
- sender_name, sender_email （可选）：发送器配置。
- subscribe_on_signup （布尔值，可选）：自动订阅新成员。
ghost_get_newsletters -通过筛选检索所有新闻通讯。
- limit, page, filter, order （可选）：查询选项。
ghost_get_newsletter -按ID检索单个时事通讯。
- id （string，必填）：时事通讯的ID。
ghost_update_newsletter -更新现有的时事通讯。
- id （string，必填）：要更新的时事通讯的ID。
- name, description，发件人设置（可选）。
ghost_delete_newsletter -永久删除新闻稿。
- id （string，必填）：要删除的新闻稿的ID。

层级工具（5个工具）

ghost_create_tier -创建新的成员级别。
- name （字符串，必填）：层名称。
- description （字符串，可选）：层描述。
- monthly_price, yearly_price （数字，可选）：以美分计价。
- currency （字符串，可选）：3个字母的货币代码（例如“USD”）。
- benefits （数组，可选）：等级优势列表。
ghost_get_tiers -使用筛选检索所有层。
- type （可选）：按“免费”或“付费”筛选。
- limit, page, filter （可选）：查询选项。
ghost_get_tier -按ID检索单个层。
- id （string，必填）：层的ID。
ghost_update_tier -更新现有层。
- id （字符串，必填）：要更新的层的ID。
- 定价、福利和其他级别字段（可选）。
ghost_delete_tier -永久删除层。
- id （string，必填）：要删除的层的ID。

安装

NPM安装（推荐）

使用npm全局安装：

npm install -g @jgardner04/ghost-mcp-server

或者使用npx运行而不安装：

npx @jgardner04/ghost-mcp-server

可用命令

安装后，以下CLI命令可用：

ghost-mcp-server：启动Express REST API服务器和MCP服务器（默认设置）
ghost-mcp：启动支持传输配置的改进型MCP服务器

配置

在运行服务器之前，请配置Ghost Admin API凭据：

创建一个 .env 工作目录中的文件：

# Required:
GHOST_ADMIN_API_URL=https://your-ghost-site.com
GHOST_ADMIN_API_KEY=your_admin_api_key

在“集成”->“自定义集成”下的“Ghost管理员”设置中查找Ghost管理员API URL和密钥。

运行服务器

安装和配置后：

# Using the global installation
ghost-mcp-server

# Or using npx
npx @jgardner04/ghost-mcp-server

# Run the improved MCP server (recommended for MCP clients)
ghost-mcp

# Or with specific transport
MCP_TRANSPORT=stdio ghost-mcp
MCP_TRANSPORT=http ghost-mcp
MCP_TRANSPORT=websocket ghost-mcp

可用的npm脚本

对于开发，可以使用以下脚本：

脚本	描述
`npm start`	启动Express REST API+MCP服务器
`npm run start:mcp`	仅启动改进的MCP服务器
`npm run start:mcp:stdio`	带stdio传输的MCP服务器
`npm run start:mcp:http`	具有HTTP/SSE传输的MCP服务器
`npm run start:mcp:websocket`	带WebSocket传输的MCP服务器
`npm test`	运行测试
`npm run test:coverage`	使用覆盖率报告运行测试
`npm run lint`	检查代码是否存在linting错误
`npm run lint:fix`	自动修复掉毛错误

MCP客户端配置

Ghost MCP服务器可与任何兼容MCP的客户端配合使用。下面是最常见客户端的快速启动配置。有关包括WebSocket和HTTP/SSE传输的完整指南，请参阅 docs/MCP_CLIENT_SETUP.md.

Claude Code（包括Sidedoc项目）

创建一个 .mcp.json 位于项目根目录的文件（例如 Sidedoc存储库):

{
  "mcpServers": {
    "ghost": {
      "command": "npx",
      "args": ["-y", "@jgardner04/ghost-mcp-server"],
      "env": {
        "GHOST_ADMIN_API_URL": "https://your-ghost-site.com",
        "GHOST_ADMIN_API_KEY": "your_admin_api_key"
      }
    }
  }
}

Claude Code将自动检测此文件，并在该项目中提供所有34个Ghost MCP工具。您还可以全局注册服务器：

claude mcp add ghost \
  --scope user \
  --command npx \
  --args "-y @jgardner04/ghost-mcp-server" \
  --env GHOST_ADMIN_API_URL=https://your-ghost-site.com \
  --env GHOST_ADMIN_API_KEY=your_admin_api_key

提示： 不要承诺 .mcp.json 包含真实API密钥的文件。添加 .mcp.json 给你的 .gitignore 或来自的源凭据 .env 文件。

克劳德桌面

将服务器添加到Claude Desktop配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ghost": {
      "command": "npx",
      "args": ["-y", "@jgardner04/ghost-mcp-server"],
      "env": {
        "GHOST_ADMIN_API_URL": "https://your-ghost-site.com",
        "GHOST_ADMIN_API_KEY": "your_admin_api_key"
      }
    }
  }
}

保存文件后重新启动Claude Desktop。

光标

打开 光标设置→ 特性→ MCP服务器，单击 添加服务器，并提供：

姓名： ghost
命令： npx -y @jgardner04/ghost-mcp-server
环境变量： GHOST_ADMIN_API_URL 和 GHOST_ADMIN_API_KEY

开发设置

对于想要修改源代码的贡献者或高级用户：

克隆存储库:

git clone https://github.com/jgardner04/Ghost-MCP-Server.git
cd Ghost-MCP-Server

安装依赖项:
```
npm install
```
配置环境变量: 创建一个 .env 项目根目录中的文件（请参阅上面的配置部分）。

从源代码运行:

npm start
# OR directly:
# node src/index.js

开发模式（使用nodemon）: 对于自动重启的开发：
```
npm run dev
```

故障排除

401 Ghost未经授权的错误： 检查你的 GHOST_ADMIN_API_URL 和 GHOST_ADMIN_API_KEY 在 .env 文件是正确的，并且Ghost中的自定义集成已启用。
MCP服务器连接问题： 确保MCP服务器正在运行（检查控制台日志）。验证端口(MCP_PORT，默认3001）未被防火墙阻止。检查客户端是否连接到正确的地址和端口。
工具执行错误： 检查服务器控制台日志，了解特定工具实现的详细错误消息。常见问题包括无效输入（请检查中的工具模式 src/mcp_server.js 以及README指南），从下载时出现问题 imageUrl、图像处理失败或来自Ghost API的上游错误。
未找到命令： 如果 ghost-mcp-server 或 ghost-mcp 全局安装后找不到命令，请确保npm的全局bin目录在您的PATH中。你可以通过以下方式找到它 npm bin -g.
依赖安装问题： 确保您安装了兼容的Node.js版本（Node.js 18.0.0或更高版本-请参阅要求部分）。对于全局安装问题，请尝试 npm install -g @jgardner04/ghost-mcp-server --force。对于开发设置，请尝试删除 node_modules 和 package-lock.json 跑步 npm install 再一次。