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

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:

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.