# Ghost MCP

A [Model Context Protocol](https://modelcontextprotocol.io) server that gives Claude, Gemini, and any other MCP-compatible AI full access to your [Ghost CMS](https://ghost.org) via the Ghost Admin API.

**Documentation languages:** [English](docs/en/) · [Français](docs/fr/) · [Español](docs/es/)

---

## Features

- **47 tools** across 10 resource types — posts, members, users, tags, tiers, offers, newsletters, invites, roles, and webhooks
- **7 MCP resources** — fetch any Ghost entity by URI (e.g. `post://abc123`)
- **2 built-in prompts** — `summarize-post` and `content-audit`
- **Typed error handling** — Ghost API errors are caught and surfaced as clean messages, not raw stack traces
- **Full tool descriptions** — every tool includes a plain-English description and per-parameter hints so the LLM understands exactly what to pass
- **Zero `any` types** — proper TypeScript interfaces throughout

---

## Quick start

### 1. Prerequisites

- Node.js >= 18
- A Ghost site with Admin API access (Ghost Pro or self-hosted)

### 2. Get your Ghost credentials

1. In your Ghost Admin dashboard, go to **Settings → Integrations**
2. Click **Add custom integration**, give it a name (e.g. "MCP")
3. Copy the **Admin API Key** — it looks like `id:secret`

### 3. Pick your AI client

No cloning or building required. Every integration below uses `npx @antoinefamibelle/ghost-mcp` to run the server on demand.

---

## Client integrations

### Claude Desktop

The recommended integration. MCP is a native feature of Claude Desktop.

**Config file location:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "ghost": {
      "command": "npx",
      "args": ["-y", "@antoinefamibelle/ghost-mcp"],
      "env": {
        "GHOST_API_URL": "https://yourblog.com",
        "GHOST_ADMIN_API_KEY": "your_id:your_secret",
        "GHOST_API_VERSION": "v5.0"
      }
    }
  }
}
```

Restart Claude Desktop. A hammer icon will appear in the chat input indicating all 47 tools are available.

---

### Claude Code (CLI)

Run this once in your terminal — Claude Code will persist the server across sessions:

```bash
claude mcp add ghost \
  --command npx \
  --args "-y,@antoinefamibelle/ghost-mcp" \
  -e GHOST_API_URL=https://yourblog.com \
  -e GHOST_ADMIN_API_KEY=your_id:your_secret
```

Or add it manually to `.claude/mcp.json` in your project using the same JSON shape as Claude Desktop above.

---

### Gemini CLI

Google's [Gemini CLI](https://github.com/google-gemini/gemini-cli) supports MCP servers natively.

**Config file:** `~/.gemini/settings.json`

```json
{
  "mcpServers": {
    "ghost": {
      "command": "npx",
      "args": ["-y", "@antoinefamibelle/ghost-mcp"],
      "env": {
        "GHOST_API_URL": "https://yourblog.com",
        "GHOST_ADMIN_API_KEY": "your_id:your_secret",
        "GHOST_API_VERSION": "v5.0"
      }
    }
  }
}
```

Start a session with `gemini` and the Ghost tools will be available automatically.

---

### ChatGPT

ChatGPT does not support MCP. OpenAI uses a separate plugin/GPT Actions system based on OpenAPI specs. There is no direct integration path — you would need to wrap this server in an HTTP REST layer to use it with ChatGPT.

---

### Other MCP-compatible clients

Any client that speaks the MCP stdio transport can run this server. The command is always:

```bash
npx -y @antoinefamibelle/ghost-mcp
```

with `GHOST_API_URL` and `GHOST_ADMIN_API_KEY` set in the environment.

---

## Tools reference

### Posts (5 tools)

| Tool | Description |
|---|---|
| `posts_browse` | List posts with filters, pagination, and sorting |
| `posts_read` | Fetch a single post by ID or slug |
| `posts_add` | Create a new post (draft or published) |
| `posts_edit` | Update an existing post |
| `posts_delete` | Permanently delete a post |

### Members (5 tools)

| Tool | Description |
|---|---|
| `members_browse` | List members with filters |
| `members_read` | Fetch a single member by ID or email |
| `members_add` | Add a new member |
| `members_edit` | Update a member's details or subscriptions |
| `members_delete` | Remove a member |

### Users (4 tools)

| Tool | Description |
|---|---|
| `users_browse` | List staff users |
| `users_read` | Fetch a single user by ID, email, or slug |
| `users_edit` | Update a user's profile |
| `users_delete` | Delete a staff user |

### Tags (5 tools)

| Tool | Description |
|---|---|
| `tags_browse` | List all tags |
| `tags_read` | Fetch a single tag by ID or slug |
| `tags_add` | Create a new tag |
| `tags_edit` | Update a tag |
| `tags_delete` | Delete a tag |

### Tiers (5 tools)

| Tool | Description |
|---|---|
| `tiers_browse` | List membership tiers |
| `tiers_read` | Fetch a single tier |
| `tiers_add` | Create a paid tier |
| `tiers_edit` | Update a tier |
| `tiers_delete` | Delete a tier |

### Offers (5 tools)

| Tool | Description |
|---|---|
| `offers_browse` | List promotional offers |
| `offers_read` | Fetch an offer by ID or code |
| `offers_add` | Create a discount or trial offer |
| `offers_edit` | Update an offer's display text |
| `offers_delete` | Delete an offer |

### Newsletters (5 tools)

| Tool | Description |
|---|---|
| `newsletters_browse` | List newsletters |
| `newsletters_read` | Fetch a single newsletter |
| `newsletters_add` | Create a new newsletter |
| `newsletters_edit` | Update newsletter settings |
| `newsletters_delete` | Delete a newsletter |

### Invites (3 tools)

| Tool | Description |
|---|---|
| `invites_browse` | List pending staff invitations |
| `invites_add` | Send a staff invitation |
| `invites_delete` | Cancel an invitation |

### Roles (2 tools)

| Tool | Description |
|---|---|
| `roles_browse` | List available roles |
| `roles_read` | Fetch a single role by ID or name |

### Webhooks (5 tools)

| Tool | Description |
|---|---|
| `webhooks_browse` | List configured webhooks |
| `webhooks_read` | Fetch a single webhook |
| `webhooks_add` | Create a new webhook |
| `webhooks_edit` | Update a webhook |
| `webhooks_delete` | Delete a webhook |

---

## MCP Resources

Access Ghost entities directly by URI:

| URI pattern | Returns |
|---|---|
| `post://{post_id}` | Full post object including tags and authors |
| `user://{user_id}` | Staff user with roles |
| `member://{member_id}` | Member with labels and subscriptions |
| `tier://{tier_id}` | Tier with pricing details |
| `offer://{offer_id}` | Promotional offer details |
| `newsletter://{newsletter_id}` | Newsletter configuration |
| `blog://info` | Site settings and metadata |

---

## Built-in prompts

### `summarize-post`

Fetches a Ghost post and asks the LLM to write a concise 2-3 sentence summary.

**Parameter:** `postId` — the Ghost post ID

### `content-audit`

Fetches recent posts and asks the LLM to audit them for title quality, tagging consistency, publishing cadence, author diversity, and content strategy.

**Parameters:**
- `limit` — number of posts to include (default: 10)
- `status` — post status to filter by: `published` | `draft` | `scheduled` (default: `published`)

---

## Environment variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `GHOST_API_URL` | Yes | — | Your Ghost site URL, e.g. `https://yourblog.com` |
| `GHOST_ADMIN_API_KEY` | Yes | — | Admin API key in `id:secret` format |
| `GHOST_API_VERSION` | No | `v5.0` | Ghost API version |

See [docs/en/configuration.md](docs/en/configuration.md) for full details.

---

## Documentation

| Document | Contents |
|---|---|
| [docs/en/configuration.md](docs/en/configuration.md) | Environment variables, Claude Desktop setup, troubleshooting |
| [docs/en/tools.md](docs/en/tools.md) | Complete tool reference with all parameters |
| [docs/en/resources.md](docs/en/resources.md) | MCP resource URI reference |
| [docs/en/development.md](docs/en/development.md) | Build, test, and extend the server |

---

## License

MIT