preangelleo/ghost-blog-mcp-server

🚀 Ghost Blog MCP Server

AI-powered Ghost Blog management via MCP protocol with smart dual-mode architecture.

🌐 Live Server: https://animagent.ai/mcp/ghost-blog-smart ✅ Online

🌟 Features

🏛️ Ghost CMS Integration

• Complete blog post CRUD operations
• Advanced filtering and search
• Bulk operations for multiple posts
• SEO metadata management
• Custom excerpts and tags

🤖 AI-Powered Content Creation

• Smart Gateway: Automatically routes content through optimal processing path
• Content Generation: Create blog posts, titles, excerpts, and meta descriptions
• Content Improvement: Enhance, expand, shorten, or optimize existing content
• Multi-language Translation: Support for any target language with cultural adaptation

🎨 Dual AI Image Generation

• Google Imagen-4: Professional quality, artistic images
• Replicate Flux-dev: Ultra-fast generation (3-7 seconds), photorealistic
• Automatic Fallback: Switches between providers for maximum reliability
• Smart Prompting: AI-optimized image descriptions from blog content

🔐 Security & Authentication

• GitHub OAuth: Secure authentication with user permissions
• Role-based Access: Viewer, Editor, and Admin permission levels
• JWT Token Management: Secure Ghost CMS API access
• Input Validation: Comprehensive validation with Zod schemas

📊 Monitoring & Analytics

• Blog Metrics: Comprehensive analytics and insights
• Sentry Integration: Optional error tracking and performance monitoring
• User Activity: Track content creation and modifications
• Service Status: Real-time health checks and diagnostics

🚀 Quick Start for Users

Ready to use our Ghost Blog MCP server with Claude? Just follow these 3 simple steps:

🔐 Step 1: Get Your Credentials

👉 CLICK HERE TO AUTHENTICATE & GET CREDENTIALS 👈

This will:

• Authenticate you with GitHub
• Generate your unique MCP credentials
• Show you the 4 values needed for setup

💻 Step 2: Add to Claude Desktop

For Claude Desktop users:

1. Open Claude Desktop application
2. Go to Settings ⚙️ → "MCP" section
3. Click "Add Custom Connector"
4. Copy-paste these 4 values from the authentication page:
   • Name: Ghost Blog MCP Smart
   • Remote MCP server URL: https://animagent.ai/mcp/ghost-blog-smart/mcp
   • OAuth Client ID: [Your unique client ID]
   • OAuth Client Secret: [Your unique client secret]
5. Click "Add" to finish setup

For Claude Web users (claude.ai):

1. Visit claude.ai in your browser
2. Look for "Custom Connectors" or "MCP" in your settings
3. Add the same 4 values from your authentication page

✅ Step 3: Test Your Connection

Ask Claude: "What Ghost blog tools are available?" or "Show me my blog analytics"

That's it! 🎉 You now have access to 15 powerful Ghost blog management tools.

Need help? The authentication page will guide you back here with your exact credentials. No complex setup - just click, copy, paste, and go!

🏗️ Developer Setup

Prerequisites

• Node.js 20+
• GitHub account for OAuth
• Ghost CMS instance with Admin API access
• AI Services (choose one or both):
  • Google Gemini API key (for content generation + Imagen)
  • Replicate API token (for Flux image generation)

1. Installation

# Clone the repository
git clone https://github.com/preangelleo/ghost-blog-mcp-server.git
cd ghost-blog-mcp-server

# Install dependencies
npm install

# Install Wrangler CLI globally
npm install -g wrangler

# Authenticate with Cloudflare
wrangler login

2. Environment Configuration

# Copy environment template
cp .dev.vars.example .dev.vars

# Edit .dev.vars with your configuration

Required Environment Variables:

# Ghost CMS Configuration
GHOST_ADMIN_API_KEY=your_key_id:your_secret_key
GHOST_API_URL=https://your-ghost-site.com

# GitHub OAuth
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
COOKIE_ENCRYPTION_KEY=your_random_32_char_encryption_key

# AI Services (at least one required)
GEMINI_API_KEY=your_gemini_api_key
REPLICATE_API_TOKEN=r8_your_replicate_token

# Optional: Sentry monitoring
SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id
NODE_ENV=development

3. GitHub OAuth Setup

1. Create GitHub OAuth App: Go to GitHub Developer Settings
2. Application details:
   • Name: Ghost Blog MCP Server (Local)
   • Homepage URL: http://localhost:8787
   • Callback URL: http://localhost:8787/callback
3. Copy credentials to your .dev.vars file

4. Development Server

# Start development server
npm run dev

# Server available at: http://localhost:8787
# MCP endpoint: http://localhost:8787/mcp

🔧 MCP Tools Available

The server provides 15 powerful tools based on your permission level:

📝 Content Management (Editor+)

• createBlogPost - Create new blog posts with AI image generation
• smartBlogGateway - AI-powered content analysis and creation
• updateBlogPost - Update post properties and metadata
• schedulePost - Schedule posts for future publication

📊 Content Discovery (All Users)

• getBlogPosts - List and filter posts with advanced search
• getBlogPostDetails - Get complete post information and analytics
• analyzeBlogMetrics - Comprehensive blog statistics

🤖 AI Content Tools (Editor+)

• generateBlogContent - Create content from prompts
• improveBlogContent - Enhance existing content with AI
• translateBlogContent - Multi-language translation

🎨 Image Tools (Editor+)

• generateBlogImage - Create AI images with Flux/Imagen
• updateBlogImage - Replace or generate new feature images

👨‍💼 Admin Tools (Admin Only)

• deleteBlogPost - Permanently remove blog posts
• batchManagePosts - Bulk operations on multiple posts

🔍 Utilities (All Users)

• checkServiceStatus - Service health and permissions check

🌐 Usage Examples

Connect with Claude Desktop

Add to your Claude Desktop configuration (~/claude_desktop_config.json):

{
  "mcpServers": {
    "ghost-blog": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:8787/mcp"]
    }
  }
}

Example Prompts

Create a blog post:

Please create a blog post about "The Future of AI in Healthcare" with an AI-generated feature image. Make it about 800 words and include relevant tags.

Smart content creation:

Transform these scattered ideas into a complete blog post: "machine learning, faster diagnosis, privacy concerns, cost reduction, doctor training challenges"

Translate content:

Translate my latest blog post to Spanish with cultural adaptation for the Latin American audience.

Generate images:

Create a professional feature image for a blog post about "Digital Marketing Trends 2024" in 16:9 aspect ratio using Flux for speed.

Blog analytics:

Show me comprehensive analytics for my blog including post counts, most used tags, and recent activity.

📊 Permission System

👀 Viewer (All authenticated users)

• View blog posts and details
• Access analytics and metrics
• Check service status

✏️ Editor (Configured usernames)

• All viewer permissions
• Create and edit blog posts
• Use AI content and image tools
• Schedule posts

👨‍💼 Admin (Restricted usernames)

• All editor permissions
• Delete blog posts
• Batch operations
• User management

Configure permissions in src/utils/config.ts:

export const ADMIN_USERNAMES = new Set([
  'preangelleo',  // Your GitHub username
  // Add more admin usernames
]);

export const EDITOR_USERNAMES = new Set([
  'preangelleo',
  'editor1',
  'editor2'
  // Add editor usernames
]);

🚀 Deployment

Local Testing

# Test with standard version
npm run dev

# Test with Sentry monitoring
npm run dev:sentry

Production Deployment

# Create KV namespace for OAuth
wrangler kv namespace create "OAUTH_KV"

# Update wrangler.jsonc with the KV namespace ID

# Set production secrets
wrangler secret put GHOST_ADMIN_API_KEY
wrangler secret put GHOST_API_URL
wrangler secret put GITHUB_CLIENT_ID
wrangler secret put GITHUB_CLIENT_SECRET
wrangler secret put COOKIE_ENCRYPTION_KEY
wrangler secret put GEMINI_API_KEY
wrangler secret put REPLICATE_API_TOKEN
wrangler secret put SENTRY_DSN  # Optional

# Deploy to Cloudflare Workers
npm run deploy

# Or deploy with Sentry monitoring
npm run deploy:sentry

GitHub OAuth for Production

Create a new GitHub OAuth App for production:

• Homepage URL: https://your-worker-name.your-subdomain.workers.dev
• Callback URL: https://your-worker-name.your-subdomain.workers.dev/callback

🧪 Testing

MCP Inspector Testing

# Install MCP Inspector
npx @modelcontextprotocol/inspector@latest

# Test local server
# URL: http://localhost:8787/mcp

# Test production server
# URL: https://your-worker.workers.dev/mcp

Manual Testing

# Health check
curl http://localhost:8787/health

# Service info
curl http://localhost:8787/info

# Type checking
npm run type-check

# Run tests
npm test

🏗️ Architecture

ghost-blog-mcp-server/
├── src/
│   ├── index.ts              # Main MCP server
│   ├── index_sentry.ts       # Sentry-enabled server
│   ├── ghost/                # Ghost CMS integration
│   │   ├── client.ts         # Ghost API client
│   │   ├── content-creator.ts # AI content generation
│   │   ├── image-generator.ts # Dual image generation
│   │   └── smart-gateway.ts  # Intelligent routing
│   ├── tools/                # MCP tools
│   │   ├── blog-tools.ts     # Core blog management
│   │   ├── ai-tools.ts       # AI-powered tools
│   │   └── register-tools.ts # Tool registration
│   ├── auth/                 # Authentication
│   │   └── github-handler.ts # GitHub OAuth
│   ├── utils/                # Utilities
│   │   ├── config.ts         # Configuration
│   │   ├── validation.ts     # Input validation
│   │   └── errors.ts         # Error handling
│   └── types.ts             # TypeScript definitions
├── package.json
├── wrangler.jsonc           # Cloudflare Workers config
├── tsconfig.json            # TypeScript config
└── README.md               # This file

🔄 AI Services Comparison

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

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

🙏 Acknowledgments

• Ghost CMS - Excellent blogging platform
• Google Gemini - AI content generation
• Replicate - Ultra-fast image generation
• Cloudflare Workers - Serverless platform
• Model Context Protocol - AI agent integration

📞 Support

• Documentation: This README
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Made with ❤️ by leowang.net for the Ghost CMS and MCP communities