ghost-mcp/README.md

Ghost MCP Server

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 JWT Authentication for Ghost Admin API requests
• 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

Installation

Installing via Smithery

To install Ghost MCP Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @MFYDev/ghost-mcp --client claude

Manual Installation

# Clone repository
git clone git@github.com/mfydev/ghost-mcp.git
cd ghost-mcp

# Create virtual environment and install
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .

Requirements

• Python ≥ 3.12
• Running Ghost instance with Admin API access (v5.x+ recommended)
• Node.js (for testing with MCP Inspector)

Usage

Environment Variables

GHOST_API_URL=https://yourblog.com  # Your Ghost Admin API URL
GHOST_STAFF_API_KEY=your_staff_api_key                 # Your Ghost Staff API key

Usage with Claude Desktop

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

{
  "mcpServers": {
    "ghost": {
      "command": "/Users/username/.local/bin/uv",
      "args": [
        "--directory",
        "/path/to/ghost-mcp",
        "run",
        "src/main.py"
      ],
      "env": {
        "GHOST_API_URL": "your_ghost_api_url",
        "GHOST_STAFF_API_KEY": "your_staff_api_key"
      }
    }
  }
}

Testing with MCP Inspector

GHOST_API_URL=your_ghost_api_url GHOST_STAFF_API_KEY=your_staff_api_key npx @modelcontextprotocol/inspector uv --directory /path/to/ghost-mcp run src/main.py

Available Tools

Posts Management

• list_posts: List blog posts with pagination (supports both text and JSON formats)
• search_posts_by_title: Search for posts by title using exact or fuzzy matching
• read_post: Retrieve full content of a specific post in HTML or plaintext formats
• create_post: Create a new post with specified content and metadata
• update_post: Update a specific post with new content and metadata
• delete_post: Delete a specific post
• batchly_update_posts: Update multiple posts in a single request

Tags Management

• browse_tags: List all tags associated with the blog
• read_tag: Retrieve detailed information about a specific tag
• create_tag: Create a new tag with specified details
• update_tag: Update an existing tag with new information
• delete_tag: Delete a specific tag

Users Management

• list_roles: List all available roles
• create_invite: Create a new user invitation email and role_id
• list_users: List all users with detailed role information
• read_user: Get comprehensive details of a specific user
• update_user: Update an existing user's information (Please note: Ghost has not implemented the ability to update user roles via the API even though they include it in the API documentation)
• delete_user: Delete a specific user

Members Management

• list_members: List members with subscription and newsletter details
• read_member: Retrieve detailed information for a specific member, including subscriptions
• create_member: Create a new member with specified details
• update_member: Update an existing member's information

Tiers Management

• list_tiers: List all available membership tiers
• read_tier: Retrieve detailed information about a specific tier, including benefits and pricing
• create_tier: Create a new membership tier with specified details
• update_tier: Update an existing tier with new information

Offers Management

• list_offers: List promotional offers with relevant details
• read_offer: Get detailed information on a specific offer
• create_offer: Create a new promotional offer with specified details
• update_offer: Update an existing offer with new information

Newsletters Management

• list_newsletters: List all newsletters associated with the blog
• read_newsletter: Retrieve detailed settings and information for a specific newsletter
• create_newsletter: Create a new newsletter with specified details
• update_newsletter: Update an existing newsletter with new information

Webhooks Management

• create_webhook: Create a new webhook with specified details
• update_webhook: Update an existing webhook with new information
• delete_webhook: Delete a specific webhook

Available Resources

All resources follow the URI pattern: [type]://[id]

• user://{user_id}: User profiles and roles
• member://{member_id}: Member details and subscriptions
• tier://{tier_id}: Tier configurations
• offer://{offer_id}: Offer details
• newsletter://{newsletter_id}: Newsletter settings
• post://{post_id}: Post content and metadata
• blog://info: General blog information

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