Ghost CMS MCP Server

A comprehensive Model Context Protocol (MCP) server for Ghost CMS that provides full automation capabilities for Ghost blogs through AI assistants like Claude Desktop, Cursor, and other MCP-compatible clients.

✨ Features

• 🚀 Complete Ghost API Coverage - All major Ghost operations supported
• 🔐 Secure Authentication - JWT tokens for Admin API, key-based for Content API
• ⚡ Smart Rate Limiting - Built-in queue management with exponential backoff
• 🎯 Bulk Operations - Efficient mass updates and deletions
• 📝 Content Management - Full CRUD for posts, pages, members, and more
• 🏷️ Rich Metadata - SEO optimization, social media, and custom fields
• 🧪 Test-Driven Development - Comprehensive test suite with 80%+ coverage
• 📊 TypeScript - Full type safety and IntelliSense support
• 🔄 Real-time Sync - Instant updates and conflict resolution

📦 Installation

Quick Start

NPM (Recommended)

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

For Claude Desktop

macOS/Linux:

# Install package
npm install -g @ghost-cms/mcp-server

# Add to Claude Desktop config
echo '{
  "mcpServers": {
    "ghost-cms": {
      "command": "npx",
      "args": ["-y", "@ghost-cms/mcp-server"],
      "env": {
        "GHOST_URL": "https://your-site.ghost.io",
        "GHOST_ADMIN_API_KEY": "your-admin-key",
        "GHOST_CONTENT_API_KEY": "your-content-key"
      }
    }
  }
}' >> ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows (PowerShell):

# Install package
npm install -g @ghost-cms/mcp-server

# Add to Claude Desktop config
$config = @{
  mcpServers = @{
    "ghost-cms" = @{
      command = "npx"
      args = @("-y", "@ghost-cms/mcp-server")
      env = @{
        GHOST_URL = "https://your-site.ghost.io"
        GHOST_ADMIN_API_KEY = "your-admin-key"
        GHOST_CONTENT_API_KEY = "your-content-key"
      }
    }
  }
} | ConvertTo-Json -Depth 4

Add-Content -Path "$env:APPDATA\Claude\claude_desktop_config.json" -Value $config

For Claude Code CLI

# Linux/macOS/Windows
claude mcp add ghost-cms -- npx -y @ghost-cms/mcp-server

For Cursor IDE

# Install globally
npm install -g @ghost-cms/mcp-server

# Configure in Cursor settings
# Add MCP server configuration in Settings > Extensions > MCP

Manual Installation

git clone https://github.com/ghost-cms/mcp-server.git
cd mcp-server
npm install
npm run build
npm start

⚙️ Configuration

Environment Variables

Create a .env file or set environment variables:

# Required
GHOST_URL=https://your-site.ghost.io
GHOST_ADMIN_API_KEY=your-admin-key-id:your-admin-secret
GHOST_CONTENT_API_KEY=your-content-api-key

# Optional Performance Settings
RATE_LIMIT_MAX_REQUESTS=100
RATE_LIMIT_WINDOW_MS=60000
CACHE_TTL_MS=300000
CACHE_ENABLED=true

# Optional Advanced Settings
MAX_RETRY_ATTEMPTS=3
RETRY_DELAY_MS=1000
MAX_RETRY_DELAY_MS=30000
ENABLE_BULK_OPERATIONS=true
BULK_OPERATION_LIMIT=100

# Logging
LOG_LEVEL=info
LOG_FILE=ghost-mcp.log
DEBUG=false

Getting Ghost API Keys

1. Go to Ghost Admin → Integrations → Add custom integration
2. Copy the Admin API Key (format: id:secret)
3. Copy the Content API Key
4. Set your Ghost URL (your site's URL)

🛠️ Available Tools

📝 Content Management

Posts

• ghost_posts_list - List posts with advanced filters
• ghost_posts_get - Get single post by ID or slug
• ghost_posts_create - Create new post with full metadata
• ghost_posts_update - Update existing post
• ghost_posts_delete - Delete post permanently
• ghost_posts_publish - Publish draft post with email options
• ghost_posts_unpublish - Convert published post to draft
• ghost_posts_search - Search posts by content
• ghost_posts_bulk_update - Mass update multiple posts
• ghost_posts_bulk_delete - Mass delete posts (with confirmation)

Pages

• ghost_pages_list - List all pages
• ghost_pages_get - Get single page
• ghost_pages_create - Create new page
• ghost_pages_update - Update existing page
• ghost_pages_delete - Delete page

👥 Member Management

• ghost_members_list - List members with filters
• ghost_members_get - Get member details
• ghost_members_create - Create new member
• ghost_members_update - Update member info
• ghost_members_delete - Delete member
• ghost_members_import - Bulk import members
• ghost_members_export - Export member data

🏷️ Content Organization

• ghost_tags_list - List all tags
• ghost_tags_create - Create new tag
• ghost_tags_update - Update tag details
• ghost_tags_delete - Delete tag

💰 Subscription Management

• ghost_tiers_list - List membership tiers
• ghost_tiers_create - Create new tier
• ghost_tiers_update - Update tier pricing/features
• ghost_tiers_archive - Archive tier

📧 Newsletter Management

• ghost_newsletters_list - List newsletters
• ghost_newsletters_create - Create newsletter
• ghost_newsletters_update - Update newsletter settings
• ghost_newsletters_archive - Archive newsletter

🖼️ Media Management

• ghost_media_upload - Upload images and files
• ghost_media_upload_from_url - Upload from URL

⚙️ Site Management

• ghost_settings_get - Get site settings
• ghost_settings_update - Update site configuration
• ghost_users_list - List users/authors
• ghost_users_update - Update user profiles
• ghost_webhooks_create - Create webhooks
• ghost_site_info - Get site information

📋 Usage Examples

Create a Blog Post

// Use the ghost_posts_create tool
{
  "title": "My Awesome Post",
  "html": "<p>This is my post content with <strong>formatting</strong>.</p>",
  "status": "published",
  "tags": ["technology", "tutorial"],
  "meta_title": "SEO Optimized Title",
  "meta_description": "This post teaches you amazing things.",
  "featured": true,
  "custom_excerpt": "A brief summary of the post...",
  "published_at": "2024-12-25T00:00:00.000Z"
}

Bulk Update Posts

// Use the ghost_posts_bulk_update tool
{
  "filter": "status:draft+created_at:>2024-01-01",
  "data": {
    "status": "published",
    "featured": true,
    "tags": ["bulk-updated"]
  }
}

Search and Filter

// Use the ghost_posts_list tool
{
  "filter": "status:published+featured:true",
  "order": "published_at desc",
  "limit": 10,
  "include": "tags,authors",
  "fields": "title,slug,published_at,featured"
}

Create Member with Subscription

// Use the ghost_members_create tool
{
  "email": "[email protected]",
  "name": "New Subscriber",
  "labels": ["vip", "newsletter"],
  "note": "Premium subscriber",
  "subscribed": true,
  "comped": false
}

🧪 Testing

Run Tests

# All tests
npm test

# Unit tests only
npm run test:unit

# Integration tests
npm run test:integration

# With coverage
npm run test:coverage

# Watch mode for development
npm run test:watch

Test Coverage

• Unit Tests: All tools and utilities
• Integration Tests: Full API workflows
• E2E Tests: Real Ghost API interactions
• Performance Tests: Rate limiting and caching
• Security Tests: Authentication and validation

🚀 Development

Local Development

git clone https://github.com/ghost-cms/mcp-server.git
cd mcp-server
npm install
cp .env.example .env
# Edit .env with your Ghost credentials
npm run dev

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Write tests for your changes
4. Ensure all tests pass: npm test
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

Code Quality

npm run lint        # ESLint checking
npm run lint:fix    # Auto-fix issues
npm run format      # Prettier formatting
npm run build       # TypeScript compilation

🔧 Advanced Usage

Custom Rate Limiting

// Set custom rate limits per environment
process.env.RATE_LIMIT_MAX_REQUESTS = '200';
process.env.RATE_LIMIT_WINDOW_MS = '30000';

Bulk Operations

// Safe bulk operations with confirmation
{
  "filter": "status:draft+created_at:<2024-01-01",
  "confirm": true  // Required for destructive operations
}

Error Handling

The server provides detailed error messages:

• 400: Invalid request parameters
• 401: Authentication failed
• 403: Permission denied
• 404: Resource not found
• 409: Conflict (e.g., concurrent edit)
• 422: Validation error
• 429: Rate limit exceeded

📊 Performance & Monitoring

Metrics

• Request rate limiting with queue management
• Automatic retry with exponential backoff
• Response caching for read operations
• Connection pooling for optimal throughput

Logging

Structured logging with configurable levels:

LOG_LEVEL=debug    # error, warn, info, debug
LOG_FILE=ghost.log # Optional file output

🔒 Security

• API Key Protection: Keys never logged or exposed
• Request Validation: All inputs validated before API calls
• Rate Limiting: Prevents API abuse
• Secure Defaults: Conservative permissions and timeouts
• Audit Trail: Comprehensive logging of all operations

🤝 Community & Support

Getting Help

• 📚 Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 📧 Email Support

Related Projects

• Ghost CMS - The headless CMS platform
• Model Context Protocol - The protocol specification
• Claude Desktop - AI assistant with MCP support

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• The Ghost team for the excellent CMS platform
• Anthropic for the Model Context Protocol specification
• The open source community for tools and inspiration

Built with ❤️ for the Ghost and AI community

⭐ Star this repo if you find it useful!