Ghost MCP Server

A comprehensive Model Context Protocol (MCP) server for Ghost CMS, providing both read-only Content API and read/write Admin API access through FastMCP.

🎯 Features

• Complete Ghost API Coverage: Both Content API (read-only) and Admin API (read/write)
• 15+ MCP Tools: Posts, pages, tags, authors, settings, and more
• Modern Python Implementation: FastMCP 2.12.3 with async/await
• JWT Authentication: Secure Admin API access with token caching
• Robust Error Handling: 5 error categories with comprehensive logging
• Configuration Management: Environment variables with precedence
• Development Tools: Complete Docker setup and automation scripts

🚀 Quick Start

Prerequisites

• Docker and Docker Compose
• Python 3.10+ (with uv recommended)

Setup

# Clone the repository
git clone <repository-url>
cd ghost-mcp

# Complete setup from scratch
make setup

# Or step by step:
make install-uv          # Install uv package manager
make install            # Install Python dependencies
make start-ghost        # Start Ghost and database
make setup-tokens       # Extract API keys and create .env
make test              # Test the implementation

Usage

# Run the MCP server
make run

# Development mode with auto-reload
make dev

# Check system status
make status

# View container logs
make logs

📋 Available MCP Tools

Content API Tools (Read-only)

• get_posts - Get published posts with filtering/pagination
• get_post_by_id - Get single post by ID
• get_post_by_slug - Get single post by slug
• search_posts - Search posts by title/content
• get_pages - Get published pages
• get_page_by_id - Get single page by ID
• get_page_by_slug - Get single page by slug
• get_tags - Get tags with filtering
• get_tag_by_id - Get single tag by ID
• get_tag_by_slug - Get single tag by slug
• get_authors - Get authors
• get_author_by_id - Get single author by ID
• get_author_by_slug - Get single author by slug
• get_settings - Get public settings
• get_site_info - Get basic site information

Admin API Tools (Read/Write)

• create_post - Create new posts with full options
• update_post - Update existing posts
• delete_post - Delete posts
• get_admin_posts - Get posts including drafts
• create_page - Create new pages
• create_tag - Create new tags

Utility Tools

• check_ghost_connection - Test connectivity and configuration

🔧 Configuration

Configuration is managed through environment variables with precedence:

1. Environment variables
2. .env file
3. Default values

Required Variables

GHOST_URL=http://localhost:2368
GHOST_CONTENT_API_KEY=your_content_api_key_here
GHOST_ADMIN_API_KEY=your_admin_api_key_here

Optional Variables

GHOST_VERSION=v5.0
GHOST_MODE=auto          # auto, readonly, readwrite
GHOST_TIMEOUT=30
GHOST_MAX_RETRIES=3
GHOST_RETRY_BACKOFF_FACTOR=2.0

LOG_LEVEL=info           # debug, info, warning, error
LOG_STRUCTURED=true
LOG_REQUEST_ID=true

🛠️ Development

Project Structure

ghost-mcp/
├── src/ghost_mcp/
│   ├── server.py           # FastMCP server entry point
│   ├── client.py           # Ghost API client
│   ├── config.py           # Configuration management
│   ├── auth/               # Authentication modules
│   ├── tools/
│   │   ├── content/        # Content API tools
│   │   └── admin/          # Admin API tools
│   ├── types/              # Type definitions
│   └── utils/              # Utilities
├── scripts/                # Setup and test scripts
├── contracts/              # API documentation
├── docker-compose.yml      # Ghost + MySQL setup
├── Makefile               # Development commands
└── pyproject.toml         # Python project config

Available Commands

make help                # Show all commands
make setup              # Complete setup from scratch
make install            # Install dependencies with uv
make start-ghost        # Start Ghost containers
make setup-tokens       # Generate API keys
make test              # Run tests
make test-connection    # Test API connectivity
make run               # Run MCP server
make status            # Check system status
make clean             # Clean up everything

🐳 Docker Environment

The project includes a complete Docker Compose setup:

• Ghost: Latest Ghost 5.x with Alpine Linux
• MySQL 8.0: Database with health checks
• Development optimized: Logging, auto-restart, volume persistence

URLs

• Ghost Admin: http://localhost:2368/ghost/
• Ghost Site: http://localhost:2368/
• Database: localhost:3306

🔐 API Authentication

Content API

• Uses query parameter authentication
• 26-character hex API key
• Read-only access to published content

Admin API

• Uses JWT token authentication
• Format: id:secret (24-char + 64-char hex)
• 5-minute token expiration with automatic renewal
• Full read/write access

📊 Error Handling

Comprehensive error handling with 5 categories:

1. Network Errors: Connection timeouts, DNS failures
2. Authentication Errors: Invalid keys, expired tokens
3. Ghost API Errors: Ghost-specific errors with codes
4. Validation Errors: Invalid parameters, malformed data
5. File Upload Errors: Media upload failures

All errors include:

• Unique error ID
• Category classification
• Context information
• Request ID for tracing

🧪 Testing

# Test Ghost API connectivity
make test-connection

# Run all tests
make test

# Test specific functionality
python scripts/test-connection.py

📝 Logging

Structured logging with configurable levels:

• Request IDs: Track requests across components
• Structured format: JSON output for production
• Context preservation: Error context and debugging info
• Performance metrics: Request timing and retry information

🔄 Retry Logic

Robust retry mechanism:

• Exponential backoff: Configurable base delay and multiplier
• Jitter: Prevents thundering herd problems
• Max retries: Configurable retry limits
• Circuit breaker: Fail fast after repeated failures

📚 Documentation

• API Contracts: Complete Ghost API documentation in contracts/
• Type Definitions: Full type coverage with Pydantic models
• Examples: Working examples for all tools
• Development Guide: Step-by-step setup and usage

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes with tests
4. Run make test to verify
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details

🆘 Support

• Issues: GitHub issues for bugs and features
• Documentation: Check contracts/ for API details
• Logs: Use make logs for troubleshooting
• Status: Use make status for system health

---

Built with FastMCP 2.12.3 and Ghost 5.x 🚀