ghost-publisher-mcp

# Ghost Publisher MCP

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

[![npm version](https://img.shields.io/npm/v/ghost-publisher-mcp.svg)](https://www.npmjs.com/package/ghost-publisher-mcp)
[![npm downloads](https://img.shields.io/npm/dw/ghost-publisher-mcp.svg)](https://www.npmjs.com/package/ghost-publisher-mcp)
[![GitHub release](https://img.shields.io/github/v/release/BlogFactoryHQ/ghost-publisher-mcp.svg)](https://github.com/BlogFactoryHQ/ghost-publisher-mcp/releases/latest)
[![CI](https://github.com/BlogFactoryHQ/ghost-publisher-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/BlogFactoryHQ/ghost-publisher-mcp/actions/workflows/ci.yml)

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

Ghost Publisher exposes a bounded editorial surface 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.

Ghost Publisher is maintained by [BlogFactoryHQ](https://github.com/BlogFactoryHQ) and works independently. [BlogFactory](https://github.com/BlogFactoryHQ/blogfactory) is the separate multi-site, draft-only control plane; Ghost Publisher is the local Ghost-specific server for separately approved scheduling and publishing. Installing one does not install or authorize the other.

[Read the official overview and installation guide](https://blogfactory.io/open-source-tools/ghost-publisher-mcp/).

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

> Current npm and official MCP Registry release: `0.10.1`, published on 2026-08-25.

On 2026-08-16, setup discovery and a redacted dry run passed with ChatGPT desktop `26.810.41047` and its bundled Codex CLI `0.148.0-alpha.9`; a read-only connection check reached Ghost `6.42`. Cursor and Claude Desktop configuration generation is automated, but their current application runtimes were unavailable on the verification host. Please use the [client compatibility issue form](https://github.com/BlogFactoryHQ/ghost-publisher-mcp/issues/new?template=client-compatibility.yml) for redacted reports and never include an Admin key.

## Proven in a daily publishing workflow

[Ortak Alan](https://ortakalan.io/search/) uses Ghost Publisher in its maintainer-operated daily workflow across a 336-piece public archive. The team creates drafts, corrects metadata, uploads images, publishes approved batches, deploys once, and verifies the live result—at a reported cadence of five to six posts a day.

The manual version of that path took roughly 30 minutes per post. The operator now completes reviewed batches in minutes without dropping draft-first creation or public-result checks. During this publishing period, Search Console recorded 652 clicks and 65,000 impressions over three months; its latest captured 28-day view showed 500 clicks (+294%) and 51,900 impressions (+369%). This is operational outcome evidence, not a claim that this MCP alone caused organic growth. Read the [full Ortak Alan case study](docs/case-study-ortakalan.md).

## 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

[Watch the silent 60-second setup tour (4K, 60 fps)](https://github.com/BlogFactoryHQ/ghost-publisher-mcp/releases/download/v0.8.0/setup-demo-60s.mp4).

![Ghost Publisher one-command setup](https://raw.githubusercontent.com/BlogFactoryHQ/ghost-publisher-mcp/main/docs/assets/setup.png)

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. On macOS it detects apps in the system or user Applications folder; if Codex is not on `PATH`, it automatically uses the CLI bundled with the Codex or ChatGPT desktop app. 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.10.1 setup \
  --url https://your-ghost.example.com \
  --client codex \
  --key-env GHOST_SETUP_KEY \
  --yes
unset GHOST_SETUP_KEY
```

Use `--permission read-only|draft-editor|scheduler|publisher` to enforce a capability profile. `--read-only` remains an alias for `--permission read-only`; the two options cannot be combined. 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).

## Manual client configuration

Use these only when you do not want the installer to update the local client configuration. Keep the file containing your Ghost Admin key private and restart the client after editing it.

### Codex

Add this to your user-level Codex configuration:

```toml
[mcp_servers.ghost-publisher]
command = "npx"
args = ["-y", "ghost-publisher-mcp@0.10.1"]
env = { GHOST_URL = "https://your-ghost.example.com", GHOST_ADMIN_API_KEY = "your_id:your_secret", GHOST_PERMISSION_PROFILE = "publisher", 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

Add this server entry to Claude Desktop's MCP JSON configuration:

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

### Cursor

Add this server entry to Cursor's MCP JSON configuration:

```json
{
  "mcpServers": {
    "ghost-publisher": {
      "command": "npx",
      "args": ["-y", "ghost-publisher-mcp@0.10.1"],
      "env": {
        "GHOST_URL": "https://your-ghost.example.com",
        "GHOST_ADMIN_API_KEY": "your_id:your_secret",
        "GHOST_PERMISSION_PROFILE": "publisher"
      }
    }
  }
}
```

For a cautious first connection, use `GHOST_PERMISSION_PROFILE=read-only`; change it only when you are ready to create drafts or publish.

## Security and credentials

- Ghost Publisher runs as a local stdio process. Your Ghost Admin key remains in your local MCP client configuration and is never sent to a Ghost Publisher-hosted service.
- Do not paste keys into chats, issues, shell arguments, commits, screenshots, or forum posts. Use the interactive installer or your client’s local secret/configuration store.
- Draft creation is always draft-only. Publishing, scheduling, applying a change set, unpublishing, and deployment require a separate explicit confirmation.
- Start with the `read-only` permission profile and grant `draft-editor`, `scheduler`, or `publisher` only for the workflow you need.

See the [client compatibility issue form](https://github.com/BlogFactoryHQ/ghost-publisher-mcp/issues/new?template=client-compatibility.yml) for a redacted report template.

## Direct comparison

Ghost Publisher is the narrow, approval-gated option. The alternatives below intentionally expose broader Ghost administration or richer authoring surfaces; choose that breadth when you need it. The comparison reflects each project's public README on 2026-08-16.

| Project | Primary boundary | Content input | Write controls | Deliberately broader surface |
| --- | --- | --- | --- | --- |
| **Ghost Publisher MCP** | Posts, Pages, images, schedules, bounded audits, and deploy/live checks | Markdown or bounded native Ghost blocks, including the v0.9 authoring preview | Draft-first creation, permission profiles, revision checks, signed preview/apply, literal confirmation, no automatic write retry | None: deletion, members, newsletters, themes, arbitrary API calls, and remote transport are non-goals |
| [MFYDev/ghost-mcp](https://github.com/MFYDev/ghost-mcp) | General Ghost administration | Post content through entity CRUD | Standard Ghost Admin operations | Posts, users, members, tiers, offers, newsletters, tags, invites, roles, and webhooks, including deletion |
| [jgardner04/Ghost-MCP-Server](https://github.com/jgardner04/Ghost-MCP-Server) | 34 tools across seven resource types | HTML for posts and Pages | Standard create/update/delete tools | Tags, posts, Pages, members, newsletters, tiers, and site operations |
| [damusix/ghost-mcp](https://github.com/damusix/ghost-mcp) | Full Ghost Admin/Content API dispatcher plus authoring helpers | Broad native Koenig blocks or direct API payloads | Content API read-only mode; Admin mode exposes full API actions | Members, newsletters,