# 👻 Ghost CMS Admin & Newsletter MCP Server

A production-ready **Model Context Protocol (MCP)** server supporting **Streamable HTTP** (MCP Specification), **SSE**, and **stdio**, allowing AI models (Claude, Cursor, Antigravity, ChatGPT, Cline, Zed, etc.) to manage, curate, draft, publish, and administer self-hosted **Ghost CMS Blogs & Newsletters**.

Designed for standalone deployment on your VPS alongside your Ghost instance, behind Docker, Coolify, Caddy, or Nginx.

---

## ⚡ Streamable HTTP Endpoints

| Endpoint | Method | Description |
|---|---|---|
| `/mcp` | `POST` / `GET` | **MCP Streamable HTTP Transport** (Official MCP spec endpoint for stateful/stateless LLM requests & streaming) |
| `/sse` | `GET` | **Legacy Server-Sent Events (SSE)** endpoint for backwards compatibility |
| `/messages` | `POST` | **Legacy SSE messages** intake endpoint (`/messages?sessionId=...`) |
| `/health` | `GET` | Health check & Ghost connectivity status verification |
| `/` | `GET` | Overview of server status, endpoints, and Ghost site metadata |

---

## 🛠️ Included MCP Tools Catalog

### 📝 1. Posts & Newsletters
- **`ghost_list_posts`**: Search, filter, and paginate blog posts & newsletter editions (`draft`, `published`, `scheduled`, `sent`, `all`).
- **`ghost_get_post`**: Fetch full content, HTML, mobiledoc/lexical, tags, authors, and email click/delivery stats.
- **`ghost_create_post`**: Create blog posts and newsletters directly from Markdown or HTML with SEO metadata, tags, authors, excerpts, and custom scheduling.
- **`ghost_update_post`**: Edit existing posts with automatic concurrency synchronization (`updated_at`).
- **`ghost_delete_post`**: Permanently delete a post by ID.
- **`ghost_publish_and_send_newsletter`**: **One-shot publish & email broadcast** to subscriber tiers (`all`, `status:free`, `status:paid`).

### 📄 2. Static Pages
- **`ghost_list_pages`**, **`ghost_get_page`**, **`ghost_create_page`**, **`ghost_update_page`**, **`ghost_delete_page`**: Complete static pages lifecycle (About, Contact, Landing pages).

### 💌 3. Newsletters & Email Configuration
- **`ghost_list_newsletters`**: List all publication email newsletters with member counts and dispatch history.
- **`ghost_get_newsletter`**, **`ghost_create_newsletter`**, **`ghost_update_newsletter`**: Manage sender names, sender emails, reply-to, and subscriber defaults.

### 👥 4. Members & Subscribers
- **`ghost_list_members`**: Search and filter subscribers by email, name, subscription tier, and labels.
- **`ghost_get_member`**, **`ghost_create_member`**, **`ghost_update_member`**, **`ghost_delete_member`**: Subscriber profile management and complimentary tier assignments.
- **`ghost_add_member_labels`**: Append segmentation labels to members.

### 🏷️ 5. Tags, Tiers, Settings, Media & Webhooks
- **Tags**: `ghost_list_tags`, `ghost_get_tag`, `ghost_create_tag`, `ghost_update_tag`, `ghost_delete_tag` (including internal `#tags`).
- **Tiers & Offers**: `ghost_list_tiers`, `ghost_list_offers` (Free & Paid memberships, pricing, coupons).
- **Site Settings & Diagnostics**: `ghost_get_site_info`, `ghost_test_connection`.
- **Media Uploads**: `ghost_upload_image` (upload local files, web URLs, or base64 images to Ghost for feature images).
- **Webhooks**: `ghost_list_webhooks`, `ghost_create_webhook`, `ghost_delete_webhook`.

---

## 📦 MCP Resources & Prompts

### Resources
- `ghost://site/info` – Publication title, URL, version, and global configuration.
- `ghost://newsletters` – Active email newsletters with subscriber counts.
- `ghost://tiers` – Available membership tiers and pricing models.
- `ghost://posts/recent` – 10 most recent published posts.
- `ghost://members/summary` – Member counts and recent subscriber activities.

### Prompts
- `draft-blog-post` – Guided interactive template to create an SEO-optimized blog post with tags, excerpts, and formatting.
- `draft-newsletter` – Structure and write an engaging email newsletter issue ready for broadcast.
- `ghost-content-audit` – Complete editorial review of recent posts, tag hygiene, and audience growth recommendations.

---

## 🔑 Ghost Admin API Setup

1. Open your Ghost Admin dashboard (`https://your-blog.ghost.io/ghost` or `http://localhost:2368/ghost`).
2. Go to **Settings (gear icon)** ➔ **Integrations**.
3. Click **Add custom integration**.
4. Name it (e.g. `AI Admin Assistant` or `MCP Server`).
5. Copy:
   - **Admin API URL** (e.g. `http://localhost:2368` or `https://blog.yourdomain.com`)
   - **Admin API Key** (e.g. `64a7c8e2b0123456789abcde:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef`)

---

## 🚀 Coolify & VPS Deployment Alongside Ghost

### Deploying on Coolify (Zero-Config Reverse Proxy & SSL)

Coolify automatically handles Traefik reverse proxying, Let's Encrypt SSL certificates, Docker networking, and zero-downtime deploys.

1. **Create New Resource** in Coolify from your Git Repository.
2. Set **Base Directory** to `/ghost-admin-mcp` (or root if standalone repo).
3. Set **Build Pack** to `Dockerfile` and **Port** to `8765`.
4. Configure Environment Variables:
   - `GHOST_ADMIN_API_URL`: `https://blog.yourdomain.com`
   - `GHOST_ADMIN_API_KEY`: `<your-admin-api-key>`
   - `MCP_AUTH_TOKEN`: `<your-random-token>`
   - `PORT`: `8765`
   - `TRANSPORT`: `streamable-http`
5. Set **Health Check Path** to `/health`.
6. Set your domain (e.g. `https://mcp.yourdomain.com`) — Coolify handles SSL automatically!

For multi-container Docker Compose in Coolify, see [COOLIFY.md](./COOLIFY.md).

---

## 🔌 Connecting Remote AI Clients

### Streamable HTTP (MCP Remote Client / Cursor / Claude)

Configure your remote client to connect to:
- **URL**: `https://mcp.yourdomain.com/mcp`
- **Headers**:
  ```json
  {
    "Authorization": "Bearer your_custom_secret_bearer_token"
  }
  ```

### Local Stdio (Claude Desktop / Cursor local fallback)

```json
{
  "mcpServers": {
    "ghost-admin": {
      "command": "node",
      "args": ["/path/to/ghost-admin-mcp/dist/index.js"],
      "env": {
        "GHOST_ADMIN_API_URL": "https://blog.yourdomain.com",
        "GHOST_ADMIN_API_KEY": "your_key_id:your_secret_key"
      }
    }
  }
}
```

---

## 🧪 Testing

```bash
bun test
```

## 📄 License

MIT