ghost-publisher-mcp

# Ghost Publisher MCP

**Write with your AI. Publish safely to Ghost.**

An unofficial, local-first MCP server for creating and managing Ghost posts and Pages, scheduling posts, uploading images, publishing approved batches, triggering static-site rebuilds, and verifying rendered content.

Ghost Publisher deliberately exposes 23 bounded editorial tools instead of mirroring the full Ghost Admin API. It has no delete, member, newsletter-send, theme, arbitrary-query, remote HTTP, OAuth, or built-in AI billing surface.

> This project is not affiliated with or endorsed by the Ghost Foundation.

> Current release: `0.4.1`, published to npm and the official MCP Registry and verified against Ghost 5 and Ghost 6.

## Requirements

- Node.js 22 or newer
- A Ghost custom integration Admin API key
- Optional: a deploy hook and public post/page URL templates for headless/static sites

Create a custom integration in **Ghost Admin → Settings → Integrations**, then copy its Admin API key.

## One-command setup

Run this in a private terminal:

```bash
npx -y ghost-publisher-mcp@latest setup --url https://your-ghost.example.com
```

The installer prompts once for the Ghost Admin API key without echoing it, detects Codex, Cursor, and Claude Desktop, verifies the Ghost connection without writing content, shows a redacted plan, and asks before changing client configuration. Generated entries pin the exact package version that ran setup, preventing surprise upgrades.

For CI or automation, inject the key into an environment variable through the platform's secret manager rather than typing it into the command or passing it as an argument:

```bash
npx -y ghost-publisher-mcp@0.4.1 setup \
  --url https://your-ghost.example.com \
  --client codex \
  --key-env GHOST_SETUP_KEY \
  --yes
unset GHOST_SETUP_KEY
```

Use `--read-only` for a nine-tool read-only installation. Use `--dry-run` to preview a fully redacted plan. Existing entries are preserved unless `--replace` is supplied. The Admin key is stored in each selected client's local user configuration; setup refuses symlinked configurations.

Ghost Publisher runs locally so the Ghost Admin key is not entrusted to another hosted service. An OpenSEO-style hosted connection would require a separately threat-modeled credential service and remains on the [future roadmap](docs/plans/future-interoperability.md).

For optional deployment, upload, live-check, and read-only settings, the equivalent full Codex configuration is:

```toml
[mcp_servers.ghost-publisher]
command = "npx"
args = ["-y", "ghost-publisher-mcp@0.4.1"]
env = { GHOST_URL = "https://your-ghost.example.com", GHOST_ADMIN_API_KEY = "your_id:your_secret", GHOST_READ_ONLY = "false", GHOST_UPLOAD_ROOTS = "/absolute/path/to/blog-assets", GHOST_DEPLOY_HOOK_URL = "https://your-host.example.com/deploy-hook", GHOST_PUBLIC_POST_URL_TEMPLATE = "https://your-site.example.com/posts/{slug}", GHOST_PUBLIC_PAGE_URL_TEMPLATE = "https://your-site.example.com/{slug}" }
```

Keep this user-level file private and do not commit it. Setup uses the user-level client locations only; advanced settings remain manual.

## Claude Desktop, Cursor, and other MCP clients

Add a stdio server to the client's MCP JSON configuration:

```json
{
  "mcpServers": {
    "ghost-publisher": {
      "command": "npx",
      "args": ["-y", "ghost-publisher-mcp@0.4.1"],
      "env": {
        "GHOST_URL": "https://your-ghost.example.com",
        "GHOST_ADMIN_API_KEY": "your_id:your_secret",
        "GHOST_READ_ONLY": "false",
        "GHOST_UPLOAD_ROOTS": "/absolute/path/to/blog-assets",
        "GHOST_PUBLIC_PAGE_URL_TEMPLATE": "https://your-site.example.com/{slug}"
      }
    }
  }
}
```

Restart the client after changing its MCP configuration.

## Configuration

| Variable | Required | Default | Purpose |
| --- | --- | --- | --- |
| `GHOST_URL` | Yes | — | Ghost instance URL; HTTPS required outside localhost and embedded credentials rejected. |
| `GHOST_ADMIN_API_KEY` | Yes | — | Admin key from a Ghost custom integration. |
| `GHOST_API_VERSION` | No | `v5.0` | Ghost Admin API compatibility version. |
| `GHOST_READ_ONLY` | No | `false` | Set to exact `true` to register only nine read tools. Exact `true`/`false` values are required. |
| `GHOST_UPLOAD_ROOTS` | For local uploads | — | Allowed absolute directories, separated by the OS path delimiter (`:` on macOS/Linux, `;` on Windows). |
| `GHOST_DEPLOY_HOOK_URL` | No | — | HTTPS endpoint receiving one non-redirecting POST after a fully successful publish/unpublish batch. |
| `GHOST_PUBLIC_POST_URL_TEMPLATE` | No | — | Public post URL with exactly one `{slug}` in its path, used by `check_live_posts`. |
| `GHOST_PUBLIC_PAGE_URL_TEMPLATE` | No | — | Public page URL with exactly one `{slug}` in its path, used by `check_live_pages` for headless sites. |

The server does not read `.env` files itself. Supply variables through the MCP client or the process environment.

## Tools

| Tool | Behavior |
| --- | --- |
| `check_connection` | Verify Ghost and report read-only mode plus optional feature availability. A configured deployment reveals only its host. |
| `list_posts` | List/search posts and obtain exact IDs plus `updated_at`. |
| `get_post` | Read one post by ID or slug with content plus complete SEO and social metadata. |
| `list_tags` | List tags with post counts. |
| `list_authors` | Search bounded public author identity fields without exposing staff email, roles, permissions, or settings. |
| `list_pages` | List/search Pages with bounded status, date, order, and pagination fields. |
| `get_page` | Read one Page by exact ID or slug with content and metadata. |
| `create_drafts` | Create up to 10 Markdown posts; always draft-only. |
| `create_page_drafts` | Create up to 10 Markdown Pages; always draft-only. |
| `update_draft` | Patch one unchanged draft. Markdown is a complete, potentially lossy body replacement and requires `body_replacement_confirmed: true`; metadata-only patches do not. |
| `update_page_draft` | Patch one unchanged Page draft with the same explicit body-replacement acknowledgement. |
| `update_published_post` | Update approved metadata on one published post with `user_confirmed: true`, save a Ghost revision, preserve published status, and never replace its body. |
| `update_published_page` | Update approved metadata on one published Page, save a revision, preserve published status, and never replace its body. |
| `upload_image` | Upload a validated local image—including one generated by Codex or another AI client—inside configured roots. |
| `publish_posts` | With `user_confirmed: true`, preflight and publish up to 25 exact drafts without email, then call the configured deployment hook exactly once after complete success. |
| `unpublish_posts` | With `user_confirmed: true`, preflight and return published posts to draft, then call the configured deployment hook exactly once after complete success. |
| `schedule_posts` | With confirmation, schedule up to 25 exact drafts for future web publication; never supplies newsletter parameters or runs a local scheduler. |
| `unschedule_posts` | With confirmation, return up to 25 exact scheduled posts to draft. |
| `publish_pages` | With confirmation, preflight and publish up to 25 exact Page drafts, then deploy once after complete success. |
| `unpublish_pages` | With confirmation, return up to 25 published Pages to draft, then deploy once after complete success. |
| `trigger_deploy` | With `user_confirmed: true`, call the configured deployment hook exactly once. It never retries automatically. |
| `check_live_posts` | Check public HTTP status and expected title text, optionally compare rendered SEO fields, and return one combined `verified` result. |
| `check_live_pages` | Re-read exact published Pages and verify server-selected public URLs, titles, canonical URLs, and configured SEO metadata. |

All successful calls return human-readable text and typed `structuredContent`.

With `GHOST_READ_ONLY=true`, write tools are not registered. The server exposes exactly `check_connection`, `list_posts`, `get_post`, `list_tags`, `list_authors`, `list_pages`, `get_page`, `check_live_posts`, and `check_live_pages`.

## Image generation

Ghost Publisher does not need a second image API key. Codex, Claude, or another host AI generates the image with its own available capability, saves the result inside `GHOST_UPLOAD_ROOTS`, and calls `upload_image`. The returned Ghost URL can then be supplied as `feature_image_url` to `create_drafts` or `update_draft`.

The AI client orchestrates those two capabilities because an MCP server cannot invoke a separate tool owned by its host. This keeps image generation on the AI subscription/account the user is already using; the MCP server only performs the Ghost-specific work.

## OpenSEO hybrid agent

Ghost Publisher can be used beside [OpenSEO](https://github.com/every-app/open-seo): OpenSEO supplies Search Console, site-audit, keyword, and SERP evidence; Ghost Publisher supplies the exact Ghost content and approval-gated write. The host agent coordinates them, so neither server stores the other's credentials or calls the other directly.

Configure [hosted OpenSEO MCP](https://openseo.so/docs/mcp) as a separate server, then select the project matching the site's public domain and target market. Google Search Console is optional; its OpenSEO tools are read-only and [do not use credits](https://openseo.so/features/mcp). Hosted OpenSEO [charges usage credits](https://openseo.so/pricing) for DataForSEO-backed work, including site audits, so the optimizer asks for approval before starting any credit-consuming operation. Ghost Publisher never receives OpenSEO credentials or billing data.

The npm package includes the optimizer skill at `.agents/skills/ghost-seo-optimizer`.

```text
Audit my published Ghost posts using OpenSEO. Prioritize query/page opportunities with
positions 5–20, meaningful impressions, or comparatively weak CTR. Prepare o