ghost-mcp

MCP server for managing Ghost blogs from AI coding editors.

Create, edit, publish, and sync blog posts directly from Claude Code, Cursor, or any MCP-compatible client.

Features

Posts — list, get, create, update, delete, publish with newsletter
Pages — list, get, update
Tags — list, create, update, delete, analyze usage patterns
Images — upload local files to Ghost CDN
Sync — push local markdown files (~/blog-drafts/) to Ghost as drafts
Newsletters — list available newsletters for email publishing

Quick Start

npx -y @uppinote/ghost-mcp@latest setup

The wizard auto-detects supported CLIs (Claude Code, Codex CLI, Gemini CLI), shows the current registration state of each, prompts for the Ghost URL + Admin API Key, and registers via each CLI's own mcp add command:

┌  ghost-mcp setup
│
◇  MCP clients
│    ⚠  Claude Code   stale — args are [...dev-clone...]
│    ○  Codex CLI     not registered
│    ○  Gemini CLI    not registered
│
◆  Ghost blog URL
│  https://your-blog.com
│
◆  Admin API Key (Ghost → Settings → Integrations)
│  ************************************
│
◆  Apply to which clients?
│  ◼ Claude Code (fix stale)
│  ◼ Codex CLI (new install)
│  ◼ Gemini CLI (new install)
│
└  Restart: Claude Code, Codex CLI, Gemini CLI

State symbols: ✓ in-sync · ⚠ stale (will fix) · ○ not registered (will install). One command covers install, update, and drift-fix across every detected CLI — re-run anytime to verify or after rotating your API key.

Each CLI is registered via its first-party command (claude mcp add -s user, codex mcp add, gemini mcp add -s user) with npx -y @uppinote/ghost-mcp@latest, so you automatically pick up new releases on the next CLI restart (npm cache TTL ~24h).

The setup wizard shows a one-time GitHub star prompt. Pass --yes to skip the prompt, or --star to star without asking.

Updating

Because the editor is registered with npx -y ...@latest, restarts pick up new versions automatically. To force-refresh immediately, clear npm's npx cache or restart the editor twice.

Manual Setup

The wizard is the recommended path for Claude Code / Codex / Gemini because each CLI owns its own config format. If you need to configure manually:

Claude Code, Codex CLI, Gemini CLI — use their first-party commands directly:

# Claude Code
claude mcp add -s user ghost-blog \
  -e GHOST_URL=https://your-blog.com \
  -e GHOST_ADMIN_API_KEY=your_id:your_hex_secret \
  -- npx -y @uppinote/ghost-mcp@latest

# Codex CLI
codex mcp add \
  --env GHOST_URL=https://your-blog.com \
  --env GHOST_ADMIN_API_KEY=your_id:your_hex_secret \
  ghost-blog -- npx -y @uppinote/ghost-mcp@latest

# Gemini CLI
gemini mcp add -s user ghost-blog \
  -e GHOST_URL=https://your-blog.com \
  -e GHOST_ADMIN_API_KEY=your_id:your_hex_secret \
  npx -y @uppinote/ghost-mcp@latest

Other MCP-compatible clients (Cursor, Claude Desktop, Windsurf, etc.) — add this entry to your client's MCP settings file:

{
  "mcpServers": {
    "ghost-blog": {
      "command": "npx",
      "args": ["-y", "@uppinote/ghost-mcp@latest"],
      "env": {
        "GHOST_URL": "https://your-blog.com",
        "GHOST_ADMIN_API_KEY": "your_id:your_hex_secret"
      }
    }
  }
}

Client	Settings file
Cursor	`~/.cursor/mcp.json`
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
Windsurf	`~/.codeium/windsurf/mcp_config.json`

Migrating from v1.0.x / v1.1.x

Earlier versions registered the server with node /path/to/dist/index.js, which doesn't auto-update. To switch to the npx flow:

Run npx -y @uppinote/ghost-mcp@latest setup. The wizard detects the old dev-clone registration as ⚠ stale and offers to replace it with npx -y @uppinote/ghost-mcp@latest. Confirm in the multiselect prompt.
Restart your CLI.
(Optional) Delete the old git clone directory.

Development (contributors)

git clone https://github.com/uppinote20/ghost-mcp.git
cd ghost-mcp
npm install
npm run build
npm run setup    # registers from local dist via the same wizard
npm test

Getting Your API Key

Ghost Admin → Settings → Integrations
Add custom integration
Copy the Admin API Key (format: id:secret)

Available Tools

Tool	Description
`ghost_list_posts`	List posts with optional status/tag/search filters
`ghost_get_post`	Get a single post by ID or slug
`ghost_create_post`	Create a new post from markdown
`ghost_update_post`	Update post content, metadata, status, visibility
`ghost_delete_post`	Delete a post (requires confirmation)
`ghost_upload_image`	Upload a local image file to Ghost
`ghost_list_newsletters`	List available newsletters
`ghost_list_pages`	List pages
`ghost_get_page`	Get a single page by ID or slug
`ghost_update_page`	Update page content and metadata
`ghost_list_tags`	List all tags with post counts
`ghost_create_tag`	Create a new tag
`ghost_update_tag`	Update a tag's name, slug, description, or visibility by ID or slug
`ghost_delete_tag`	Delete a tag by ID or slug
`ghost_analyze_tags`	Find unused, low-use, and similar tags
`ghost_push_local`	Push a local markdown file to Ghost as a draft
`ghost_sync_status`	Compare local files with Ghost posts

Markdown Formats for `ghost_push_local`

Three formats are auto-detected:

1. YAML Frontmatter (recommended)

---
slug: my-post
meta_title: SEO Title
meta_description: A short description
excerpt: Custom excerpt
tags: [dev, ghost]   # or block sequence:
# tags:
#   - dev
#   - ghost
---

# My Blog Post

Content here...

2. Plain Markdown

# My Blog Post

Content here — no metadata, Ghost auto-generates the slug.

3. Legacy Markers (internal)

Uses  /  HTML comment markers with an SEO table.

Security

HTTPS enforced for non-localhost connections
API key format validation (id:secret, hex-encoded secret)
Ghost ID and slug input validation (prevents path traversal / SSRF)
File path validation for sync operations (restricted to ~/blog-drafts/)
Symlink traversal prevention
Error message normalization (no internal details leaked)
Upload size limit (20 MB) and SVG blocked
Audit logging to stderr for all write operations

Development

npm run dev        # Watch mode (tsc --watch)
npm test           # Run tests
npm run test:watch # Watch mode tests
npm run build      # Build for production

License

MIT