Ghost MCP 服务器

这是 MFYDev/ghost-mcp 的一个分支，目前由 @hithereiamaliff 维护和改进。

此模型上下文协议 (MCP) 服务器提供了一种强大且灵活的方式，通过大语言模型 (LLM) 界面来管理您的 Ghost CMS 实例。它为您的博客管理功能提供了全面且安全的访问权限，使您能够自动化并简化内容管理工作流程。

功能特性

• 强大的 API 集成：所有 Admin API 操作均使用直接、经过身份验证的 axios 调用，确保连接稳定可靠，不依赖外部库。

• 全面的实体访问：管理文章、用户、会员、等级、优惠和时事通讯。

• 增强的错误处理：提供详细的状态码和响应正文。

• 现代传输方式：仅使用 Streamable HTTP 传输，移除了所有已弃用的 STDIO 逻辑。

• 诊断工具：包含用于排查 API 连接和配置问题的工具。

• 多租户支持：使用 mcp-key-service，因此公共/共享部署永远不会在 MCP URL 中暴露原始 Ghost 凭据。

• Firebase 分析：基于云的分析存储，使用 Firebase 实时数据库和本地文件备份。

• VPS 部署就绪：支持 Docker、Nginx 和 GitHub Actions 自动部署。

安装与使用

此 MCP 服务器可通过两种部署方式获取：

方法 1：NPM 包（推荐用于 MCP 客户端）

直接从 npm 安装：

npm install -g mcp-ghostcms

或者使用 npx（无需安装）：

npx mcp-ghostcms

在 Claude Desktop 中使用

要与 Claude Desktop 等 MCP 客户端一起使用，请将以下内容添加到您的 claude_desktop_config.json 中：

{
  "mcpServers": {
      "mcp-ghostcms": {
        "command": "npx",
        "args": ["-y", "mcp-ghostcms"],
        "env": {
            "GHOST_API_URL": "https://yourghostbloginstance.com",
            "GHOST_ADMIN_API_KEY": "your_admin_api_key",
            "GHOST_API_VERSION": "v6.0"
        }
      }
    }
}

方法 2：Smithery 云平台

在 Smithery 云平台上部署并运行：

或者在本地使用 Smithery 进行开发：

git clone <this-repo>
cd ghost-mcp
npm install
npm run dev

这将在 8080 端口启动服务器，并在浏览器中打开 Smithery Playground。

方法 3：使用 MCP Key Service 自托管 VPS

对于公共/共享部署，此 MCP 服务器可以自托管在 VPS 上，并通过 mcp-key-service 解析 Ghost 凭据。用户只需注册一次其 Ghost 站点 URL 和管理密钥，即可获得一个 usr_XXXXXXXX 密钥，且只有该用户密钥会出现在 MCP URL 中。

MCP URL 格式

https://your-domain.com/ghostcms/mcp/usr_YOUR_USER_KEY

替代查询参数形式：

https://your-domain.com/ghostcms/mcp?api_key=usr_YOUR_USER_KEY

在 Claude Desktop 中的使用示例

添加到您的 claude_desktop_config.json：

{
  "mcpServers": {
    "ghost-myblog": {
      "type": "streamable-http",
      "url": "https://mcp.yourdomain.com/ghostcms/mcp/usr_YOUR_USER_KEY"
    }
  }
}

在线演示

公共实例地址：

https://mcp.techmavie.digital/ghostcms/mcp/usr_YOUR_USER_KEY

注意： 请先在 mcpkeys.techmavie.digital 注册您的 Ghost 凭据以获取 usr_ 密钥。

配置

此 MCP 服务器需要以下配置：

• GHOST_API_URL：您的 Ghost 站点 URL（仅域名，无路径），例如 https://yourghostbloginstance.com

• GHOST_ADMIN_API_KEY：您的 Ghost Admin API 密钥，格式为 id:secret（来自 Ghost Admin → Settings → Integrations）。

• GHOST_API_VERSION：Ghost API 版本（Ghost 5.x 为 v5.0，Ghost 6.x 为 v6.0）。

• GHOST_CONTENT_API_KEY（可选）：用于只读操作的 Ghost Content API 密钥。

对于托管的 HTTP 模式，请在服务器上配置 KEY_SERVICE_URL 和 KEY_SERVICE_TOKEN，如果您想使用 X-API-Key 标头保护分析端点，请设置 MCP_API_KEY。

可用资源

此 MCP 服务器提供以下 Ghost CMS 资源：

• 文章 (Posts)：发布在您 Ghost 站点上的文章和内容。

• 会员 (Members)：您站点的注册用户和订阅者。

• 时事通讯 (Newsletters)：通过 Ghost 管理和发送的电子邮件通讯。

• 优惠 (Offers)：为会员提供的促销优惠和折扣。

• 邀请 (Invites)：邀请新用户或员工加入您的 Ghost 站点。

• 角色 (Roles)：Ghost 管理后台中的用户角色和权限。

• 标签 (Tags)：用于文章和内容的组织标签。

• 等级 (Tiers)：会员的订阅等级和计划。

• 用户 (Users)：管理员用户和员工账户。

• Webhook：针对外部服务的自动化事件通知。

可用工具

此 MCP 服务器提供了广泛的工具来管理您的 Ghost CMS。这些工具通过模型上下文协议公开，允许对您博客的资源进行全方位的 CRUD（创建、读取、更新、删除）操作。以下是可用工具集的概述：

文章

• 浏览文章：列出文章，支持可选的过滤、分页和排序。

• 读取文章：通过 ID 或别名获取文章。

• 添加文章：创建带有标题、内容和状态的新文章。

• 编辑文章：通过 ID 更新现有文章。

• 删除文章：通过 ID 删除文章。

会员

• 浏览会员：列出会员，支持过滤和分页。

• 读取会员：通过 ID 或电子邮件获取会员。

• 添加会员：创建新会员。

• 编辑会员：更新会员详细信息。

• 删除会员：删除会员。

时事通讯

• 浏览时事通讯：列出时事通讯。

• 读取时事通讯：通过 ID 获取时事通讯。

• 添加时事通讯：创建新时事通讯。

• 编辑时事通讯：更新时事通讯详细信息。

• 删除时事通讯：删除时事通讯。

优惠

• 浏览优惠：列出优惠。

• 读取优惠：通过 ID 获取优惠。

• 添加优惠：创建新优惠。

• 编辑优惠：更新优惠详细信息。

• 删除优惠：删除优惠。

邀请

• 浏览邀请：列出邀请。

• 添加邀请：创建新邀请。

• 删除邀请：删除邀请。

角色

• 浏览角色：列出角色。

• 读取角色：通过 ID 获取角色。

标签

• 浏览标签：列出标签。

• 读取标签：通过 ID 或别名获取标签。

• 添加标签：创建新标签。

• 编辑标签：更新标签详细信息。

• 删除标签：删除标签。

等级

• 浏览等级：列出等级。

• 读取等级：通过 ID 获取等级。

• 添加等级：创建新等级。

• 编辑等级：更新等级详细信息。

• 删除等级：删除等级。

用户

• 浏览用户：列出用户。

• 读取用户：通过 ID 或别名获取用户。

• 编辑用户：更新用户详细信息。

• 删除用户：删除用户。

Webhook

• 浏览 Webhook：列出 Webhook。

• 添加 Webhook：创建新 Webhook。

• 删除 Webhook：删除 Webhook。

每个工具都可以通过 MCP 协议访问，并可从兼容的客户端调用。有关详细的参数模式和用法，请参阅 src/tools/ 中的源代码。

错误处理与诊断

此分支包含增强的错误处理功能，可提供有关 API 故障的详细信息：

• 捕获并报告 HTTP 状态码

• 错误消息中包含完整的响应正文

• 启动时记录运行时配置

• 提供诊断工具以排查连接问题：

  • admin_site_ping：测试 Ghost Admin API 端点是否可达

  • config_echo：显示当前的 Ghost API 配置（已屏蔽密钥）

这些改进使得诊断常见问题变得更加容易，例如：

• API URL 格式不正确

• Admin API 密钥缺失或格式错误

• API 版本不匹配

• 网络/代理配置问题

开发

设置

1. 克隆仓库

2. 安装依赖：npm install

3. 创建一个包含您的 Ghost 配置的 .env 文件：

   GHOST_API_URL=https://yourghostbloginstance.com
   GHOST_ADMIN_API_KEY=your_admin_api_key
   GHOST_API_VERSION=v6.0

4. 构建项目：npm run build

5. 启动开发服务器：npm run dev

故障排除

如果您遇到身份验证或“资源未找到”错误：

1. 验证您的 Ghost Admin API 密钥是否为正确的 id:secret 格式。

2. 确保您的 GHOST_API_URL 是您的 Ghost 实例的正确域名。

3. 使用 admin_site_ping 工具验证 Admin API 端点是否可达。

4. 检查服务器日志以查看实际使用的配置。

MCP Streamable HTTP 要求

此服务器实现了具有适当会话管理和 Accept 标头处理的 MCP Streamable HTTP 传输。服务器会自动将 text/event-stream 注入 Accept 标头，并为每个请求创建隔离的传输实例，以防止会话冲突。

使用正确的 MCP 初始化测试端点：

# Test MCP initialization (proper way to test)
curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
  "https://mcp.techmavie.digital/ghostcms/mcp/usr_YOUR_USER_KEY"

# Expected response (SSE format):
# event: message
# data: {"result":{"protocolVersion":"2024-11-05","capabilities":{...},"serverInfo":{...}},"jsonrpc":"2.0","id":1}

注意： 没有 MCP 初始化的简单 GET/POST 请求将返回协议错误，如 "Bad Request: Server not initialized" - 这是预期行为。该端点需要正确的 MCP 协议握手。

对于 MCP 客户端（Claude Desktop, Claude iOS, Claude Code）：

• MCP 客户端会自动处理初始化协议和会话管理

• 确保您的 MCP URL 在客户端配置中格式正确

• 对于 Claude iOS，请使用带有您 usr_ 密钥的完整 MCP URL 的 Connectors 功能

• 对于 Claude Code，请将服务器添加到您的 MCP 设置中，类型为 streamable-http

会话管理：

• 服务器为每个 HTTP 请求创建一个新的传输实例（无状态模式）

• 每个客户端连接都会自动获得一个唯一的会话 ID

• 多个客户端可以同时连接而不会发生会话冲突

• 会话在响应发送后会自动清理

常见错误与解决方案：

VPS 部署

此 MCP 服务器完全支持通过 Docker、Nginx 和 GitHub Actions 自动部署进行自托管 VPS 部署。

架构

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Claude/MCP     │────▶│  Nginx Proxy    │────▶│  Docker         │
│  Client         │     │  /ghostcms/     │     │  Container      │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                        │
                                                        ▼
                                                ┌─────────────────┐
                                                │  Ghost CMS      │
                                                │  Admin API      │
                                                └─────────────────┘

部署文件

仓库包含：

• Dockerfile - 使用 Node.js 20-alpine 的容器配置

• docker-compose.yml - 带有分析和 Firebase 凭据卷的 Docker 编排

• deploy/nginx-mcp.conf - Nginx 反向代理配置

• .github/workflows/deploy-vps.yml - GitHub Actions 自动部署工作流

快速部署

# On your VPS
cd /opt/mcp-servers
git clone https://github.com/hithereiamaliff/mcp-ghostcms.git ghostcms
cd ghostcms

# Build and start
docker compose up -d --build

# Check logs
docker compose logs -f

端点

Firebase 分析

此 MCP 服务器使用 Firebase 实时数据库进行基于云的分析存储，并以本地文件备份作为回退。

功能特性

• 双重存储：Firebase（主）+ 本地文件（备份）

• 持久化：数据在容器重建和部署后依然存在

• 实时：每 60 秒更新一次

• 仪表板：位于 /analytics/dashboard 的可视化分析

跟踪的数据

• 总请求数和工具调用数

• 按方法（GET, POST 等）划分的请求

• 按端点划分的请求

• 工具使用统计

• 客户端 IP 和用户代理

• 每小时请求趋势

• 最近的工具调用活动

Firebase 设置

1. 在 Firebase 控制台 创建一个 Firebase 项目

2. 启用实时数据库

3. 生成服务账户凭据（项目设置 → 服务账户）

4. 将凭据复制到您的 VPS：

# On VPS
mkdir -p /opt/mcp-servers/ghostcms/.credentials
# Copy firebase-service-account.json to this directory

# Create Docker volume
docker volume create ghostcms_firebase-credentials

# Copy to volume with correct permissions
docker run --rm \
  -v ghostcms_firebase-credentials:/credentials \
  -v /opt/mcp-servers/ghostcms/.credentials:/source:ro \
  alpine sh -c "cp /source/firebase-service-account.json /credentials/ && chown -R 1001:1001 /credentials/"

# Restart container
docker compose down
docker compose up -d

Firebase 数据结构

mcp-analytics/
  └── mcp-ghostcms/
      ├── serverStartTime
      ├── totalRequests
      ├── totalToolCalls
      ├── requestsByMethod
      ├── requestsByEndpoint
      ├── toolCalls
      ├── recentToolCalls
      ├── clientsByIp
      ├── clientsByUserAgent
      ├── hourlyRequests
      └── lastUpdated

有关详细的 Firebase 设置说明，请参阅 FIREBASE_SETUP.md。

贡献

1. Fork 仓库

2. 创建功能分支

3. 提交更改

4. 创建 Pull Request

许可证

MIT