Servidor MCP de Ghost

Este es un fork de MFYDev/ghost-mcp, ahora mantenido y mejorado por @hithereiamaliff.

Este servidor del Protocolo de Contexto de Modelo (MCP) proporciona una forma potente y flexible de gestionar tu instancia de Ghost CMS utilizando interfaces de Modelos de Lenguaje Extensos (LLM). Ofrece acceso completo y seguro a las funciones administrativas de tu blog, permitiéndote automatizar y optimizar tus flujos de trabajo de gestión de contenido.

Características

• Integración robusta de API: Utiliza llamadas directas y autenticadas de axios para todas las operaciones de la API de administración, asegurando una conexión estable y fiable que no depende de bibliotecas externas.

• Acceso integral a entidades: Gestiona publicaciones, usuarios, miembros, niveles, ofertas y boletines informativos.

• Gestión de errores mejorada: Proporciona códigos de estado y cuerpos de respuesta detallados.

• Transporte moderno: Utiliza exclusivamente el transporte HTTP Streamable, eliminando toda la lógica obsoleta de STDIO.

• Herramientas de diagnóstico: Incluye herramientas para solucionar problemas de conectividad y configuración de la API.

• Soporte multi-inquilino: Utiliza mcp-key-service para que las implementaciones públicas/compartidas nunca expongan credenciales de Ghost sin procesar en las URLs de MCP.

• Firebase Analytics: Almacenamiento de análisis basado en la nube con Firebase Realtime Database y copia de seguridad de archivos locales.

• Listo para despliegue en VPS: Soporte para Docker, Nginx y despliegue automático mediante GitHub Actions.

Instalación y uso

Este servidor MCP está disponible a través de dos métodos de despliegue:

Método 1: Paquete NPM (Recomendado para clientes MCP)

Instalar directamente desde npm:

npm install -g mcp-ghostcms

O usar con npx (no requiere instalación):

npx mcp-ghostcms

Uso con Claude Desktop

Para usar con clientes MCP como Claude Desktop, añade lo siguiente a tu claude_desktop_config.json:

{
  "mcpServers": {
      "mcp-ghostcms": {
        "command": "npx",
        "args": ["-y", "mcp-ghostcms"],
        "env": {
            "GHOST_API_URL": "https://yourghostbloginstance.com",
            "GHOST_ADMIN_API_KEY": "your_admin_api_key",
            "GHOST_API_VERSION": "v6.0"
        }
      }
    }
}

Método 2: Plataforma en la nube Smithery

Despliega y ejecuta en la plataforma en la nube de Smithery:

O para desarrollo local con Smithery:

git clone <this-repo>
cd ghost-mcp
npm install
npm run dev

Esto iniciará el servidor en el puerto 8080 y abrirá el Smithery Playground en tu navegador.

Método 3: VPS autohospedado con MCP Key Service

Para despliegues públicos/compartidos, este servidor MCP puede ser autohospedado en un VPS y resuelve las credenciales de Ghost a través de mcp-key-service. Los usuarios registran la URL de su sitio Ghost y su clave de administración una vez, reciben una clave usr_XXXXXXXX, y solo esa clave de usuario aparece en la URL de MCP.

Formato de URL de MCP

https://your-domain.com/ghostcms/mcp/usr_YOUR_USER_KEY

Forma alternativa con parámetros de consulta:

https://your-domain.com/ghostcms/mcp?api_key=usr_YOUR_USER_KEY

Ejemplo de uso con Claude Desktop

Añade a tu claude_desktop_config.json:

{
  "mcpServers": {
    "ghost-myblog": {
      "type": "streamable-http",
      "url": "https://mcp.yourdomain.com/ghostcms/mcp/usr_YOUR_USER_KEY"
    }
  }
}

Demo en vivo

Una instancia pública está disponible en:

https://mcp.techmavie.digital/ghostcms/mcp/usr_YOUR_USER_KEY

Nota: Registra tus credenciales de Ghost en mcpkeys.techmavie.digital para obtener primero una clave usr_.

Configuración

Este servidor MCP requiere la siguiente configuración:

• GHOST_API_URL: La URL de tu sitio Ghost (solo dominio, sin ruta), ej. https://yourghostbloginstance.com

• GHOST_ADMIN_API_KEY: Tu clave de API de administración de Ghost en formato id:secret (desde Ghost Admin → Settings → Integrations).

• GHOST_API_VERSION: Versión de la API de Ghost (v5.0 para Ghost 5.x, v6.0 para Ghost 6.x).

• GHOST_CONTENT_API_KEY (opcional): Tu clave de API de contenido de Ghost para operaciones de solo lectura.

Para el modo HTTP hospedado, configura KEY_SERVICE_URL y KEY_SERVICE_TOKEN en el servidor, y establece MCP_API_KEY si deseas proteger los endpoints de análisis con un encabezado X-API-Key.

Recursos disponibles

Los siguientes recursos de Ghost CMS están disponibles a través de este servidor MCP:

• Publicaciones (Posts): Artículos y contenido publicado en tu sitio Ghost.

• Miembros (Members): Usuarios registrados y suscriptores de tu sitio.

• Boletines (Newsletters): Boletines informativos por correo electrónico gestionados y enviados a través de Ghost.

• Ofertas (Offers): Ofertas promocionales y descuentos para miembros.

• Invitaciones (Invites): Invitaciones para que nuevos usuarios o personal se unan a tu sitio Ghost.

• Roles: Roles de usuario y permisos dentro de la administración de Ghost.

• Etiquetas (Tags): Etiquetas organizativas para publicaciones y contenido.

• Niveles (Tiers): Niveles de suscripción y planes para miembros.

• Usuarios (Users): Usuarios administradores y cuentas de personal.

• Webhooks: Notificaciones automáticas de eventos a servicios externos.

Herramientas disponibles

Este servidor MCP proporciona una amplia gama de herramientas para gestionar tu Ghost CMS. Estas herramientas se exponen a través del Protocolo de Contexto de Modelo y permiten una gama completa de operaciones CRUD (Crear, Leer, Actualizar, Eliminar) en los recursos de tu blog. A continuación, se muestra una descripción general del conjunto de herramientas disponibles:

Publicaciones

• Explorar publicaciones: Lista publicaciones con filtros opcionales, paginación y ordenación.

• Leer publicación: Recupera una publicación por ID o slug.

• Añadir publicación: Crea una nueva publicación con título, contenido y estado.

• Editar publicación: Actualiza una publicación existente por ID.

• Eliminar publicación: Elimina una publicación por ID.

Miembros

• Explorar miembros: Lista miembros con filtros y paginación.

• Leer miembro: Recupera un miembro por ID o correo electrónico.

• Añadir miembro: Crea un nuevo miembro.

• Editar miembro: Actualiza los detalles del miembro.

• Eliminar miembro: Elimina un miembro.

Boletines

• Explorar boletines: Lista boletines informativos.

• Leer boletín: Recupera un boletín por ID.

• Añadir boletín: Crea un nuevo boletín.

• Editar boletín: Actualiza los detalles del boletín.

• Eliminar boletín: Elimina un boletín.

Ofertas

• Explorar ofertas: Lista ofertas.

• Leer oferta: Recupera una oferta por ID.

• Añadir oferta: Crea una nueva oferta.

• Editar oferta: Actualiza los detalles de la oferta.

• Eliminar oferta: Elimina una oferta.

Invitaciones

• Explorar invitaciones: Lista invitaciones.

• Añadir invitación: Crea una nueva invitación.

• Eliminar invitación: Elimina una invitación.

Roles

• Explorar roles: Lista roles.

• Leer rol: Recupera un rol por ID.

Etiquetas

• Explorar etiquetas: Lista etiquetas.

• Leer etiqueta: Recupera una etiqueta por ID o slug.

• Añadir etiqueta: Crea una nueva etiqueta.

• Editar etiqueta: Actualiza los detalles de la etiqueta.

• Eliminar etiqueta: Elimina una etiqueta.

Niveles

• Explorar niveles: Lista niveles.

• Leer nivel: Recupera un nivel por ID.

• Añadir nivel: Crea un nuevo nivel.

• Editar nivel: Actualiza los detalles del nivel.

• Eliminar nivel: Elimina un nivel.

Usuarios

• Explorar usuarios: Lista usuarios.

• Leer usuario: Recupera un usuario por ID o slug.

• Editar usuario: Actualiza los detalles del usuario.

• Eliminar usuario: Elimina un usuario.

Webhooks

• Explorar webhooks: Lista webhooks.

• Añadir webhook: Crea un nuevo webhook.

• Eliminar webhook: Elimina un webhook.

Cada herramienta es accesible a través del protocolo MCP y puede ser invocada desde clientes compatibles. Para obtener esquemas de parámetros detallados y uso, consulta el código fuente en src/tools/.

Gestión de errores y diagnóstico

Este fork incluye una gestión de errores mejorada que proporciona información detallada sobre los fallos de la API:

• Se capturan y reportan los códigos de estado HTTP

• Se incluyen los cuerpos de respuesta completos en los mensajes de error

• La configuración en tiempo de ejecución se registra al inicio

• Se dispone de herramientas de diagnóstico para solucionar problemas de conectividad:

  • admin_site_ping: Comprueba si el endpoint de la API de administración de Ghost es accesible

  • config_echo: Muestra la configuración actual de la API de Ghost (con la clave enmascarada)

Estas mejoras facilitan mucho el diagnóstico de problemas comunes como:

• Formato de URL de API incorrecto

• Claves de API de administración faltantes o mal formadas

• Desajustes en la versión de la API

• Problemas de configuración de red/proxy

Desarrollo

Configuración

1. Clona el repositorio

2. Instala las dependencias: npm install

3. Crea un archivo .env con tu configuración de Ghost:

   GHOST_API_URL=https://yourghostbloginstance.com
   GHOST_ADMIN_API_KEY=your_admin_api_key
   GHOST_API_VERSION=v6.0

4. Construye el proyecto: npm run build

5. Inicia el servidor de desarrollo: npm run dev

Solución de problemas

Si encuentras errores de autenticación o "Recurso no encontrado":

1. Verifica que tu clave de API de administración de Ghost esté en el formato correcto id:secret.

2. Asegúrate de que tu GHOST_API_URL sea el dominio correcto para tu instancia de Ghost.

3. Usa la herramienta admin_site_ping para verificar que el endpoint de la API de administración sea accesible.

4. Revisa los registros del servidor para ver la configuración real que se está utilizando.

Requisitos de MCP Streamable HTTP

Este servidor implementa el transporte MCP Streamable HTTP con una gestión de sesiones adecuada y manejo de encabezados Accept. El servidor inyecta automáticamente text/event-stream en los encabezados Accept y crea instancias de transporte aisladas por solicitud para evitar conflictos de sesión.

Probando el endpoint con la inicialización adecuada de MCP:

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Claude/MCP     │────▶│  Nginx Proxy    │────▶│  Docker         │
│  Client         │     │  /ghostcms/     │     │  Container      │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                        │
                                                        ▼
                                                ┌─────────────────┐
                                                │  Ghost CMS      │
                                                │  Admin API      │
                                                └─────────────────┘

Nota: Las solicitudes GET/POST simples sin inicialización MCP devolverán errores de protocolo como "Bad Request: Server not initialized" - este es el comportamiento esperado. El endpoint requiere un protocolo de enlace MCP adecuado.

Para clientes MCP (Claude Desktop, Claude iOS, Claude Code):

• Los clientes MCP manejan automáticamente el protocolo de inicialización y la gestión de sesiones

• Asegúrate de que tu URL de MCP esté correctamente formateada en la configuración de tu cliente

• Para Claude iOS, usa la función Connectors con la URL completa de MCP usando tu clave usr_

• Para Claude Code, añade el servidor a tu configuración MCP con el tipo streamable-http

Gestión de sesiones:

• El servidor crea una nueva instancia de transporte para cada solicitud HTTP (patrón sin estado)

• Cada conexión de cliente obtiene un ID de sesión único automáticamente

• Múltiples clientes pueden conectarse simultáneamente sin conflictos de sesión

• Las sesiones se limpian automáticamente después de que se envían las respuestas

Errores comunes y soluciones:

Despliegue en VPS

Este servidor MCP incluye soporte completo para despliegue en VPS autohospedado con Docker, Nginx y despliegue automático mediante GitHub Actions.

Arquitectura

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Claude/MCP     │────▶│  Nginx Proxy    │────▶│  Docker         │
│  Client         │     │  /ghostcms/     │     │  Container      │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                        │
                                                        ▼
                                                ┌─────────────────┐
                                                │  Ghost CMS      │
                                                │  Admin API      │
                                                └─────────────────┘

Archivos de despliegue

El repositorio incluye:

• Dockerfile - Configuración del contenedor con Node.js 20-alpine

• docker-compose.yml - Orquestación de Docker con volúmenes para análisis y credenciales de Firebase

• deploy/nginx-mcp.conf - Configuración de proxy inverso Nginx

• .github/workflows/deploy-vps.yml - Flujo de trabajo de despliegue automático de GitHub Actions

Despliegue rápido

# On your VPS
cd /opt/mcp-servers
git clone https://github.com/hithereiamaliff/mcp-ghostcms.git ghostcms
cd ghostcms

# Build and start
docker compose up -d --build

# Check logs
docker compose logs -f

Endpoints

Firebase Analytics

Este servidor MCP utiliza Firebase Realtime Database para el almacenamiento de análisis basado en la nube con copia de seguridad de archivos locales como respaldo.

Características

• Almacenamiento dual: Firebase (principal) + archivo local (respaldo)

• Persistente: Los datos sobreviven a reconstrucciones y despliegues de contenedores

• Tiempo real: Se actualiza cada 60 segundos

• Panel: Análisis visual en /analytics/dashboard

Datos rastreados

• Total de solicitudes y llamadas a herramientas

• Solicitudes por método (GET, POST, etc.)

• Solicitudes por endpoint

• Estadísticas de uso de herramientas

• IPs de clientes y agentes de usuario

• Tendencias de solicitudes por hora

• Actividad reciente de llamadas a herramientas

Configuración de Firebase

1. Crea un proyecto de Firebase en Firebase Console

2. Habilita Realtime Database

3. Genera credenciales de cuenta de servicio (Configuración del proyecto → Cuentas de servicio)

4. Copia las credenciales a tu VPS:

# On VPS
mkdir -p /opt/mcp-servers/ghostcms/.credentials
# Copy firebase-service-account.json to this directory

# Create Docker volume
docker volume create ghostcms_firebase-credentials

# Copy to volume with correct permissions
docker run --rm \
  -v ghostcms_firebase-credentials:/credentials \
  -v /opt/mcp-servers/ghostcms/.credentials:/source:ro \
  alpine sh -c "cp /source/firebase-service-account.json /credentials/ && chown -R 1001:1001 /credentials/"

# Restart container
docker compose down
docker compose up -d

Estructura de datos de Firebase

mcp-analytics/
  └── mcp-ghostcms/
      ├── serverStartTime
      ├── totalRequests
      ├── totalToolCalls
      ├── requestsByMethod
      ├── requestsByEndpoint
      ├── toolCalls
      ├── recentToolCalls
      ├── clientsByIp
      ├── clientsByUserAgent
      ├── hourlyRequests
      └── lastUpdated

Para obtener instrucciones detalladas sobre la configuración de Firebase, consulta FIREBASE_SETUP.md.

Contribución

1. Haz un fork del repositorio

2. Crea una rama de características

3. Confirma los cambios

4. Crea una solicitud de extracción (pull request)

Licencia

MIT