Ghost MCP Server

What is Ghost MCP Server about?

Ghost MCP Server exposes Ghost CMS functionality through the Model Context Protocol, allowing large language models to interact with posts, members, newsletters, offers, and other site resources directly from chat interfaces.

How to use Ghost MCP Server?

1. Install the package via NPM (e.g., npx -y @fanyangmeng/ghost-mcp).
2. Configure required environment variables: GHOST_API_URL, GHOST_ADMIN_API_KEY, and optionally GHOST_API_VERSION.
3. Add the server definition to an MCP‑compatible client configuration (e.g., Claude Desktop) using the npx command and the environment variables.
4. Invoke the provided tools (browse, read, add, edit, delete) from the LLM client to manage Ghost resources.

Key Features of Ghost MCP Server

• Secure communication with Ghost Admin API using the official @tryghost/admin-api client.
• Full CRUD toolset for posts, members, newsletters, offers, invites, roles, tags, tiers, users, and webhooks.
• Advanced search with fuzzy and exact matching.
• Human‑readable, detailed output for all entities.
• Robust error handling via custom GhostError.
• Integrated logging accessible through the MCP context.

Use Cases of Ghost MCP Server

• Content creation workflow: Ask Claude to draft, edit, or publish blog posts without leaving the chat interface.
• Subscriber management: Retrieve member information, add new subscribers, or update subscription tiers via natural language commands.
• Newsletter automation: Create and schedule newsletters programmatically through an LLM.
• Promotions: Generate and manage offers or discount codes on the fly.
• Team administration: Add or edit user roles and invites using conversational prompts.

FAQ from the Ghost MCP Server

Q: Do I need Python to run this server? A: No. The server has been rewritten in TypeScript and is distributed as an NPM package.

Q: Which environment variables are required? A: GHOST_API_URL (your site URL) and GHOST_ADMIN_API_KEY (admin key). GHOST_API_VERSION defaults to v5.0 if omitted.

Q: How is the server started? A: Include it in the MCP client configuration; the client will invoke npx -y @fanyangmeng/ghost-mcp automatically.

Q: Can I run the server in Docker? A: Yes. The migration simplifies Docker usage; just set the same environment variables inside the container.

Q: What if I encounter an error? A: Errors are returned as GhostError with clear messages; check the logs provided through the MCP context for details.

Ghost MCP Server

‼️ Important Notice: Python to TypeScript Migration

I've completely rewritten the Ghost MCP Server from Python to TypeScript in this v0.1.0 release. This major change brings several benefits:

• Simplified installation: Now available as an NPM package (@fanyangmeng/ghost-mcp)
• Improved reliability: Uses the official @tryghost/admin-api client instead of custom implementation
• Better maintainability: TypeScript provides type safety and better code organization
• Streamlined configuration: Simple environment variable setup

Breaking Changes

• Python dependencies are no longer required
• Configuration method has changed (now using Node.js environment variables)
• Docker deployment has been simplified
• Different installation process (now using NPM)

Please see the below updated documentation for details on migrating from the Python version. If you encounter any issues, feel free to open an issue on GitHub.

---

A Model Context Protocol (MCP) server for interacting with Ghost CMS through LLM interfaces like Claude. This server provides secure and comprehensive access to your Ghost blog, leveraging JWT authentication and a rich set of MCP tools for managing posts, users, members, tiers, offers, and newsletters.

Features

• Secure Ghost Admin API requests with @tryghost/admin-api
• Comprehensive entity access including posts, users, members, tiers, offers, and newsletters
• Advanced search functionality with both fuzzy and exact matching options
• Detailed, human-readable output for Ghost entities
• Robust error handling using custom GhostError exceptions
• Integrated logging support via MCP context for enhanced troubleshooting

Usage

To use this with MCP clients, for instance, Claude Desktop, add the following to your claude_desktop_config.json:

{
  "mcpServers": {
      "ghost-mcp": {
        "command": "npx",
        "args": ["-y", "@fanyangmeng/ghost-mcp"],
        "env": {
            "GHOST_API_URL": "https://yourblog.com",
            "GHOST_ADMIN_API_KEY": "your_admin_api_key",
            "GHOST_API_VERSION": "v5.0"
        }
      }
    }
}

Available Resources

The following Ghost CMS resources are available through this MCP server:

• Posts: Articles and content published on your Ghost site.
• Members: Registered users and subscribers of your site.
• Newsletters: Email newsletters managed and sent via Ghost.
• Offers: Promotional offers and discounts for members.
• Invites: Invitations for new users or staff to join your Ghost site.
• Roles: User roles and permissions within the Ghost admin.
• Tags: Organizational tags for posts and content.
• Tiers: Subscription tiers and plans for members.
• Users: Admin users and staff accounts.
• Webhooks: Automated event notifications to external services.

Available Tools

This MCP server exposes a comprehensive set of tools for managing your Ghost CMS via the Model Context Protocol. Each resource provides a set of operations, typically including browsing, reading, creating, editing, and deleting entities. Below is a summary of the available tools:

Posts

• Browse Posts: List posts with optional filters, pagination, and ordering.
• Read Post: Retrieve a post by ID or slug.
• Add Post: Create a new post with title, content, and status.
• Edit Post: Update an existing post by ID.
• Delete Post: Remove a post by ID.

Members

• Browse Members: List members with filters and pagination.
• Read Member: Retrieve a member by ID or email.
• Add Member: Create a new member.
• Edit Member: Update member details.
• Delete Member: Remove a member.

Newsletters

• Browse Newsletters: List newsletters.
• Read Newsletter: Retrieve a newsletter by ID.
• Add Newsletter: Create a new newsletter.
• Edit Newsletter: Update newsletter details.
• Delete Newsletter: Remove a newsletter.

Offers

• Browse Offers: List offers.
• Read Offer: Retrieve an offer by ID.
• Add Offer: Create a new offer.
• Edit Offer: Update offer details.
• Delete Offer: Remove an offer.

Invites

• Browse Invites: List invites.
• Add Invite: Create a new invite.
• Delete Invite: Remove an invite.

Roles

• Browse Roles: List roles.
• Read Role: Retrieve a role by ID.

Tags

• Browse Tags: List tags.
• Read Tag: Retrieve a tag by ID or slug.
• Add Tag: Create a new tag.
• Edit Tag: Update tag details.
• Delete Tag: Remove a tag.

Tiers

• Browse Tiers: List tiers.
• Read Tier: Retrieve a tier by ID.
• Add Tier: Create a new tier.
• Edit Tier: Update tier details.
• Delete Tier: Remove a tier.

Users

• Browse Users: List users.
• Read User: Retrieve a user by ID or slug.
• Edit User: Update user details.
• Delete User: Remove a user.

Webhooks

• Browse Webhooks: List webhooks.
• Add Webhook: Create a new webhook.
• Delete Webhook: Remove a webhook.

Each tool is accessible via the MCP protocol and can be invoked from compatible clients. For detailed parameter schemas and usage, see the source code in src/tools/.

Error Handling

Ghost MCP Server employs a custom GhostError exception to handle API communication errors and processing issues. This ensures clear and descriptive error messages to assist with troubleshooting.

Contributing

1. Fork repository
2. Create feature branch
3. Commit changes
4. Create pull request

License

MIT