Skip to main content
Glama

Ghost MCP Server

npm version CI License: MIT Coverage

This project (ghost-mcp-server) implements a Model Context Protocol (MCP) Server that allows an MCP client (like Cursor or Claude Desktop) to interact with a Ghost CMS instance via defined tools.

Requirements

  • Node.js 18.0.0 or higher

  • Ghost Admin API URL and Key

Related MCP server: Ghost MCP Server

Ghost MCP Server Details

This server exposes Ghost CMS management functions as MCP tools, allowing an AI client like Cursor or Claude Desktop to manage a Ghost blog.

An MCP client can discover these resources and tools by querying the running MCP server (typically listening on port 3001 by default) at its root endpoint (e.g., http://localhost:3001/). The server responds with its capabilities according to the Model Context Protocol specification.

Resources Defined

  • ghost/tag: Represents a tag in Ghost CMS. Contains id, name, slug, description.

  • ghost/post: Represents a post in Ghost CMS. Contains id, title, slug, html, status, feature_image, published_at, tags, metadata fields.

  • ghost/page: Represents a page in Ghost CMS. Similar to posts but without tag support.

  • ghost/member: Represents a member/subscriber in Ghost CMS. Contains id, email, name, status, labels, subscriptions.

  • ghost/newsletter: Represents a newsletter in Ghost CMS. Contains id, name, description, sender settings.

  • ghost/tier: Represents a membership tier in Ghost CMS. Contains id, name, description, pricing, benefits.

(Refer to src/mcp_server.js for full resource schemas.)

Tools Defined

The Ghost MCP Server provides 34 tools across 7 resource types. Below is a comprehensive guide:


Tag Tools (5 tools)

  1. ghost_create_tag - Creates a new tag.

    • name (string, required): The name for the new tag.

    • description (string, optional): A description for the tag.

    • slug (string, optional): A URL-friendly slug (auto-generated if omitted).

  2. ghost_get_tags - Retrieves a list of tags with optional filtering.

    • name (string, optional): Filter tags by exact name.

    • limit, page, order (optional): Pagination and sorting options.

  3. ghost_get_tag - Retrieves a single tag by ID or slug.

    • id (string, optional): The ID of the tag.

    • slug (string, optional): The slug of the tag.

    • include (string, optional): Additional resources to include (e.g., "count.posts").

  4. ghost_update_tag - Updates an existing tag.

    • id (string, required): The ID of the tag to update.

    • name, description, slug (optional): Fields to update.

  5. ghost_delete_tag - Deletes a tag permanently.

    • id (string, required): The ID of the tag to delete.


Image Tools (1 tool)

  1. ghost_upload_image - Downloads, processes, and uploads an image to Ghost.

    • imageUrl (string, required): A publicly accessible URL of the image.

    • alt (string, optional): Alt text (auto-generated if omitted).

    • Returns: { url, alt } - the Ghost URL and alt text.

    • Usage Note: Call this first to get a Ghost image URL before creating posts/pages.


Post Tools (6 tools)

  1. ghost_create_post - Creates a new post.

    • title (string, required): The title of the post.

    • html (string, required): The main content in HTML format.

    • status (string, optional): 'draft', 'published', or 'scheduled'.

    • tags (array, optional): Tag names (auto-created if missing).

    • published_at (ISO date, optional): Required if status is 'scheduled'.

    • feature_image, feature_image_alt, feature_image_caption (optional): Featured image settings.

    • custom_excerpt, meta_title, meta_description (optional): SEO fields.

  2. ghost_get_posts - Retrieves posts with pagination and filtering.

    • status (optional): Filter by 'published', 'draft', 'scheduled', or 'all'.

    • limit, page, filter, order, include (optional): Query options.

  3. ghost_get_post - Retrieves a single post by ID or slug.

    • id (string, optional): The ID of the post.

    • slug (string, optional): The slug of the post.

    • include (string, optional): Relations to include (e.g., "tags,authors").

  4. ghost_search_posts - Searches posts by title/content.

    • query (string, required): Search query.

    • status (optional): Filter by status.

    • limit (optional): Max results (1-50).

  5. ghost_update_post - Updates an existing post.

    • id (string, required): The ID of the post to update.

    • All other post fields are optional.

  6. ghost_delete_post - Deletes a post permanently.

    • id (string, required): The ID of the post to delete.


Page Tools (6 tools)

  1. ghost_create_page - Creates a new page (pages do NOT support tags).

    • title (string, required): The title of the page.

    • html (string, required): The main content in HTML format.

    • status, published_at, feature_image, SEO fields (optional).

  2. ghost_get_pages - Retrieves pages with pagination and filtering.

    • limit, page, filter, order, include (optional): Query options.

  3. ghost_get_page - Retrieves a single page by ID or slug.

    • id (string, optional): The ID of the page.

    • slug (string, optional): The slug of the page.

  4. ghost_search_pages - Searches pages by title/content.

    • query (string, required): Search query.

    • status, limit (optional): Filtering options.

  5. ghost_update_page - Updates an existing page.

    • id (string, required): The ID of the page to update.

  6. ghost_delete_page - Deletes a page permanently.

    • id (string, required): The ID of the page to delete.


Member Tools (6 tools)

  1. ghost_create_member - Creates a new member/subscriber.

    • email (string, required): The member's email address.

    • name (string, optional): The member's name.

    • note (string, optional): Internal notes about the member.

    • labels (array, optional): Labels to assign.

    • newsletters (array, optional): Newsletter IDs to subscribe to.

  2. ghost_get_members - Retrieves members with pagination and filtering.

    • limit, page, filter, order, include (optional): Query options.

  3. ghost_get_member - Retrieves a single member by ID or email.

    • id (string, optional): The ID of the member.

    • email (string, optional): The email of the member.

  4. ghost_search_members - Searches members by name or email.

    • query (string, required): Search query.

    • limit (optional): Max results (1-50).

  5. ghost_update_member - Updates an existing member.

    • id (string, required): The ID of the member to update.

    • email, name, note, labels, newsletters (optional).

  6. ghost_delete_member - Deletes a member permanently.

    • id (string, required): The ID of the member to delete.


Newsletter Tools (5 tools)

  1. ghost_create_newsletter - Creates a new newsletter.

    • name (string, required): The newsletter name.

    • description (string, optional): Newsletter description.

    • sender_name, sender_email (optional): Sender configuration.

    • subscribe_on_signup (boolean, optional): Auto-subscribe new members.

  2. ghost_get_newsletters - Retrieves all newsletters with filtering.

    • limit, page, filter, order (optional): Query options.

  3. ghost_get_newsletter - Retrieves a single newsletter by ID.

    • id (string, required): The ID of the newsletter.

  4. ghost_update_newsletter - Updates an existing newsletter.

    • id (string, required): The ID of the newsletter to update.

    • name, description, sender settings (optional).

  5. ghost_delete_newsletter - Deletes a newsletter permanently.

    • id (string, required): The ID of the newsletter to delete.


Tier Tools (5 tools)

  1. ghost_create_tier - Creates a new membership tier.

    • name (string, required): The tier name.

    • description (string, optional): Tier description.

    • monthly_price, yearly_price (number, optional): Pricing in cents.

    • currency (string, optional): 3-letter currency code (e.g., "USD").

    • benefits (array, optional): List of tier benefits.

  2. ghost_get_tiers - Retrieves all tiers with filtering.

    • type (optional): Filter by 'free' or 'paid'.

    • limit, page, filter (optional): Query options.

  3. ghost_get_tier - Retrieves a single tier by ID.

    • id (string, required): The ID of the tier.

  4. ghost_update_tier - Updates an existing tier.

    • id (string, required): The ID of the tier to update.

    • Pricing, benefits, and other tier fields (optional).

  5. ghost_delete_tier - Deletes a tier permanently.

    • id (string, required): The ID of the tier to delete.

Installation

Install globally using npm:

npm install -g @jgardner04/ghost-mcp-server

Or use npx to run without installing:

npx @jgardner04/ghost-mcp-server

Available Commands

After installation, the following CLI commands are available:

  • ghost-mcp-server: Starts the Express REST API server and MCP server (default)

  • ghost-mcp: Starts the improved MCP server with transport configuration support

Configuration

Before running the server, configure your Ghost Admin API credentials:

  1. Create a .env file in your working directory:

    # Required:
    GHOST_ADMIN_API_URL=https://your-ghost-site.com
    GHOST_ADMIN_API_KEY=your_admin_api_key
  2. Find your Ghost Admin API URL and Key in your Ghost Admin settings under Integrations -> Custom Integrations.

Running the Server

After installation and configuration:

# Using the global installation
ghost-mcp-server

# Or using npx
npx @jgardner04/ghost-mcp-server

# Run the improved MCP server (recommended for MCP clients)
ghost-mcp

# Or with specific transport
MCP_TRANSPORT=stdio ghost-mcp
MCP_TRANSPORT=http ghost-mcp
MCP_TRANSPORT=websocket ghost-mcp

Available npm Scripts

For development, the following scripts are available:

Script

Description

npm start

Start Express REST API + MCP servers

npm run start:mcp

Start improved MCP server only

npm run start:mcp:stdio

MCP server with stdio transport

npm run start:mcp:http

MCP server with HTTP/SSE transport

npm run start:mcp:websocket

MCP server with WebSocket transport

npm test

Run tests

npm run test:coverage

Run tests with coverage report

npm run lint

Check code for linting errors

npm run lint:fix

Auto-fix linting errors

MCP Client Configuration

The Ghost MCP Server works with any MCP-compatible client. Below are quickstart configurations for the most common clients. For a complete guide including WebSocket and HTTP/SSE transports, see docs/MCP_CLIENT_SETUP.md.

Claude Code (including the Sidedoc project)

Create a .mcp.json file at the root of your project (e.g., the Sidedoc repository):

{
  "mcpServers": {
    "ghost": {
      "command": "npx",
      "args": ["-y", "@jgardner04/ghost-mcp-server"],
      "env": {
        "GHOST_ADMIN_API_URL": "https://your-ghost-site.com",
        "GHOST_ADMIN_API_KEY": "your_admin_api_key"
      }
    }
  }
}

Claude Code will automatically detect this file and make all 34 Ghost MCP tools available within that project. You can also register the server globally:

claude mcp add ghost \
  --scope user \
  --command npx \
  --args "-y @jgardner04/ghost-mcp-server" \
  --env GHOST_ADMIN_API_URL=https://your-ghost-site.com \
  --env GHOST_ADMIN_API_KEY=your_admin_api_key

Tip: Do not commit .mcp.json files that contain real API keys. Add .mcp.json to your .gitignore or source credentials from a .env file.

Claude Desktop

Add the server to your Claude Desktop configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ghost": {
      "command": "npx",
      "args": ["-y", "@jgardner04/ghost-mcp-server"],
      "env": {
        "GHOST_ADMIN_API_URL": "https://your-ghost-site.com",
        "GHOST_ADMIN_API_KEY": "your_admin_api_key"
      }
    }
  }
}

Restart Claude Desktop after saving the file.

Cursor

Open Cursor Settings → Features → MCP Servers, click Add Server, and provide:

  • Name: ghost

  • Command: npx -y @jgardner04/ghost-mcp-server

  • Environment Variables: GHOST_ADMIN_API_URL and GHOST_ADMIN_API_KEY

Development Setup

For contributors or advanced users who want to modify the source code:

  1. Clone the Repository:

    git clone https://github.com/jgardner04/Ghost-MCP-Server.git
    cd Ghost-MCP-Server
  2. Install Dependencies:

    npm install
  3. Configure Environment Variables: Create a .env file in the project root (see Configuration section above).

  4. Run from Source:

    npm start
    # OR directly:
    # node src/index.js
  5. Development Mode (using nodemon): For development with automatic restarting:

    npm run dev

Troubleshooting

  • 401 Unauthorized Error from Ghost: Check that your GHOST_ADMIN_API_URL and GHOST_ADMIN_API_KEY in the .env file are correct and that the Custom Integration in Ghost is enabled.

  • MCP Server Connection Issues: Ensure the MCP server is running (check console logs). Verify the port (MCP_PORT, default 3001) is not blocked by a firewall. Check that the client is connecting to the correct address and port.

  • Tool Execution Errors: Check the server console logs for detailed error messages from the specific tool implementation. Common issues include invalid input (check against tool schemas in src/mcp_server.js and the README guide), problems downloading from imageUrl, image processing failures, or upstream errors from the Ghost API.

  • Command Not Found: If ghost-mcp-server or ghost-mcp commands are not found after global installation, ensure npm's global bin directory is in your PATH. You can find it with npm bin -g.

  • Dependency Installation Issues: Ensure you have a compatible Node.js version installed (Node.js 18.0.0 or higher - see Requirements section). For global installation issues, try npm install -g @jgardner04/ghost-mcp-server --force. For development setup, try removing node_modules and package-lock.json and running npm install again.

Available Tools

35 tools
ghost_create_memberB

Creates a new member (subscriber) in Ghost CMS.

Inputs: email (required), name, note, subscribed, +3 more.

ghost_create_newsletterC

Creates a new newsletter in Ghost CMS with customizable sender settings and display options.

Inputs: name (required), description, slug, sender_name, +17 more.

ghost_create_pageB

Creates a new page in Ghost CMS. Note: Pages do NOT typically use tags (unlike posts).

Inputs: title (required), html (required), slug, status, +23 more.

ghost_create_postC

Creates a new post in Ghost CMS.

Inputs: title (required), html (required), slug, status, +23 more.

ghost_create_tagC

Creates a new tag in Ghost CMS.

Inputs: name (required), slug, description, feature_image, +13 more.

ghost_create_tierC

Creates a new tier (membership level) in Ghost CMS with pricing and benefits.

Inputs: name (required), description, slug, active, +8 more.

ghost_delete_memberA

Deletes a member from Ghost CMS by ID. This operation is permanent and cannot be undone.

Inputs: id (required).

ghost_delete_newsletterB

Deletes a newsletter from Ghost CMS by ID. This operation is permanent and cannot be undone.

Inputs: id (required).

ghost_delete_pageA

Deletes a page from Ghost CMS by ID. This operation is permanent and cannot be undone.

Inputs: id (required).

ghost_delete_postB

Deletes a post from Ghost CMS by ID. This operation is permanent and cannot be undone.

Inputs: id (required).

ghost_delete_tagB

Deletes a tag from Ghost CMS by ID. This operation is permanent and cannot be undone.

Inputs: id (required).

ghost_delete_tierB

Deletes a tier (membership level) from Ghost CMS by ID. This operation is permanent and cannot be undone.

Inputs: id (required).

ghost_get_memberA

Retrieves a single member from Ghost CMS by ID or email. Provide either id OR email.

Inputs: id, email.

ghost_get_membersB

Retrieves a list of members (subscribers) from Ghost CMS with optional filtering, pagination, and includes.

Inputs: limit, page, filter, include, +1 more.

ghost_get_newsletterB

Retrieves a single newsletter from Ghost CMS by ID.

Inputs: id (required).

ghost_get_newslettersB

Retrieves a list of newsletters from Ghost CMS with optional filtering.

Inputs: limit, page, filter, order.

ghost_get_pageB

Retrieves a single page from Ghost CMS by ID or slug.

Inputs: id, slug, include.

ghost_get_pagesA

Retrieves a list of pages from Ghost CMS with pagination, filtering, and sorting options.

Inputs: limit, page, filter, include, +3 more.

ghost_get_postB

Retrieves a single post from Ghost CMS by ID or slug.

Inputs: id, slug, include.

ghost_get_postsB

Retrieves a list of posts from Ghost CMS with pagination, filtering, and sorting options.

Inputs: limit, page, filter, include, +4 more.

ghost_get_tagB

Retrieves a single tag from Ghost CMS by ID or slug.

Inputs: id, slug, include.

ghost_get_tagsA

Retrieves a list of tags from Ghost CMS with pagination, filtering, sorting, and relation inclusion. Supports filtering by name, slug, visibility, or custom NQL filter expressions.

Inputs: name, slug, visibility, limit, +4 more.

ghost_get_tierB

Retrieves a single tier (membership level) from Ghost CMS by ID.

Inputs: id (required).

ghost_get_tiersA

Retrieves a list of tiers (membership levels) from Ghost CMS with optional filtering by type (free/paid).

Inputs: limit, page, filter, include, +1 more.

ghost_search_membersB

Searches for members by name or email in Ghost CMS.

Inputs: query (required), limit.

ghost_search_pagesB

Search for pages in Ghost CMS by query string with optional status filtering.

Inputs: query (required), status, limit.

ghost_search_postsB

Search for posts in Ghost CMS by query string with optional status filtering.

Inputs: query (required), status, limit.

ghost_set_feature_imageA

Uploads an image and assigns it as the feature image of a post or page (with optional alt text and caption) in one call. Accepts the same imageUrl/imagePath/imageBase64 input modes as ghost_upload_image. Returns the updated resource. If the update fails after the upload, the error response includes the orphaned image URL.

Inputs: type (required), id (required), imageUrl, imagePath, +6 more.

ghost_update_memberB

Updates an existing member in Ghost CMS. All fields except id are optional.

Inputs: id (required), email, name, note, +4 more.

ghost_update_newsletterB

Updates an existing newsletter in Ghost CMS. Can update name, description, sender settings, and display options.

Inputs: id (required), name, description, slug, +18 more.

ghost_update_pageB

Updates an existing page in Ghost CMS. Can update title, content, status, images, and SEO fields. Only the provided fields are changed; omitted fields remain unchanged.

Inputs: id (required), title, html, slug, +24 more.

ghost_update_postA

Updates an existing post in Ghost CMS. Can update title, content, status, tags, images, and SEO fields. Only the provided fields are changed; omitted fields remain unchanged. Note: tags and authors arrays are fully replaced, not merged with existing values.

Inputs: id (required), title, html, slug, +24 more.

ghost_update_tagC

Updates an existing tag in Ghost CMS.

Inputs: id (required), name, slug, description, +14 more.

ghost_update_tierC

Updates an existing tier (membership level) in Ghost CMS. Can update pricing, benefits, and other tier properties.

Inputs: id (required), name, description, slug, +9 more.

ghost_upload_imageA

Uploads an image to Ghost CMS. Accepts a remote URL, a local file path (when GHOST_MCP_IMAGE_ROOT is configured), or a base64 payload. Returns the Ghost image URL, alt text, and ref (when Ghost echoes it).

Inputs: imageUrl, imagePath, imageBase64, mimeType, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 35 tools

    Disambiguation5/5

    Each tool targets a distinct resource-action pair (member, newsletter, page, post, tag, tier, image) with clear boundaries. Even search and get operations are differentiated by query type, avoiding ambiguity.

    Naming Consistency5/5

    All tools follow the pattern ghost_<action>_<resource> with consistent verb usage (create, delete, get, update, search, upload, set). Singular nouns for single-item retrieval and plural for lists, making the set predictable.

    Tool Count4/5

    35 tools is on the higher side but justified by the comprehensive CRUD coverage for 6 resource types plus image handling. Each tool serves a clear purpose without redundancy, though the count is slightly above typical optimal range.

    Completeness5/5

    The tool surface covers create, read (single/list), update, delete, and search for main resources, along with image upload and feature image assignment. No obvious gaps exist for Ghost CMS content management workflows.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers