Ghost MCP Server

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)

6. 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)

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

8. 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.

9. 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").

10. ghost_search_posts - Searches posts by title/content.

    • query (string, required): Search query.

    • status (optional): Filter by status.

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

11. ghost_update_post - Updates an existing post.

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

    • All other post fields are optional.

12. ghost_delete_post - Deletes a post permanently.

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

Page Tools (6 tools)

13. 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).

14. ghost_get_pages - Retrieves pages with pagination and filtering.

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

15. 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.

16. ghost_search_pages - Searches pages by title/content.

    • query (string, required): Search query.

    • status, limit (optional): Filtering options.

17. ghost_update_page - Updates an existing page.

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

18. ghost_delete_page - Deletes a page permanently.

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

Member Tools (6 tools)

19. 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.

20. ghost_get_members - Retrieves members with pagination and filtering.

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

21. 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.

22. ghost_search_members - Searches members by name or email.

    • query (string, required): Search query.

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

23. ghost_update_member - Updates an existing member.

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

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

24. ghost_delete_member - Deletes a member permanently.

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

Newsletter Tools (5 tools)

25. 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.

26. ghost_get_newsletters - Retrieves all newsletters with filtering.

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

27. ghost_get_newsletter - Retrieves a single newsletter by ID.

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

28. ghost_update_newsletter - Updates an existing newsletter.

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

    • name, description, sender settings (optional).

29. ghost_delete_newsletter - Deletes a newsletter permanently.

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

Tier Tools (5 tools)

30. 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.

31. ghost_get_tiers - Retrieves all tiers with filtering.

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

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

32. ghost_get_tier - Retrieves a single tier by ID.

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

33. ghost_update_tier - Updates an existing tier.

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

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

34. ghost_delete_tier - Deletes a tier permanently.

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

Installation

NPM Installation (Recommended)

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:

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.