Strapi MCP

Un servidor MCP para Strapi CMS, que proporciona acceso a tipos de contenido y entradas a través del protocolo MCP.

GitHub
25
Prueba este MCPPatrocinado

Documentación

Strapi MCP

Un servidor MCP para Strapi CMS, que proporciona acceso a tipos de contenido y entradas a través del Protocolo de Contexto de Modelo (Model Context Protocol).

Descripción general

Este servidor MCP se integra con cualquier instancia de Strapi CMS para proporcionar:

  • Acceso a los tipos de contenido de Strapi como recursos
  • Herramientas para crear y actualizar tipos de contenido en Strapi
  • Herramientas para gestionar entradas de contenido (crear, leer, actualizar, eliminar)
  • Soporte para Strapi en modo de desarrollo
  • Manejo robusto de errores con diagnósticos claros y guía de solución de problemas
  • Validación de configuración para prevenir problemas comunes de configuración

Configuración

Variables de Entorno

Se recomienda usar un archivo .env en la raíz del proyecto para almacenar tus credenciales.

  • STRAPI_URL: La URL de tu instancia de Strapi (por defecto: http://localhost:1337)
  • STRAPI_ADMIN_EMAIL: La dirección de correo electrónico de un usuario administrador de Strapi (Recomendado para funcionalidad completa, especialmente acceso al esquema).
  • STRAPI_ADMIN_PASSWORD: La contraseña del usuario administrador de Strapi (Recomendado).
  • STRAPI_API_TOKEN: (Respaldo opcional) Un token de API. Se puede usar si no se proporcionan credenciales de administrador, pero puede tener permisos limitados.
  • STRAPI_DEV_MODE: Establécelo en "true" para habilitar funciones de modo de desarrollo (por defecto es false).

Ejemplo de archivo .env:

STRAPI_URL=http://localhost:1337
STRAPI_ADMIN_EMAIL=your_admin_email@example.com
STRAPI_ADMIN_PASSWORD=your_admin_password
# STRAPI_API_TOKEN=your_api_token_here # Optional

Importante:

  • Agrega .env a tu archivo .gitignore para evitar comprometer las credenciales
  • Evita valores de marcador de posición como "strapi_token" - el servidor valida y rechaza marcadores de posición comunes

Instalación

Instalar desde npm (Recomendado)

npm install strapi-mcp

Instalar desde el código fuente (Desarrollo)

Para las últimas funciones de desarrollo:

git clone https://github.com/l33tdawg/strapi-mcp.git
cd strapi-mcp
npm install
npm run build

Ejecución

Método recomendado (usando la configuración MCP de Cursor):

Para usuarios de Cursor, configura el servidor strapi-mcp en tu archivo ~/.cursor/mcp.json:

"strapi-mcp": {
  "command": "npx",
  "args": ["strapi-mcp"], 
  "env": {
    "STRAPI_URL": "http://localhost:1337",
    "STRAPI_ADMIN_EMAIL": "your_admin_email@example.com",
    "STRAPI_ADMIN_PASSWORD": "your_admin_password"
  }
}

Si instalaste desde el código fuente, usa la ruta directa en su lugar:

"strapi-mcp": {
  "command": "node",
  "args": ["/path/to/strapi-mcp/build/index.js"], 
  "env": {
    "STRAPI_URL": "http://localhost:1337",
    "STRAPI_ADMIN_EMAIL": "your_admin_email@example.com",
    "STRAPI_ADMIN_PASSWORD": "your_admin_password"
  }
}

Cursor gestionará automáticamente el ciclo de vida del servidor cuando se usen las herramientas de strapi-mcp.

Método alternativo (usando archivo .env):

Asegúrate de haber compilado el proyecto (npm run build). Luego ejecuta el servidor usando Node.js v20.6.0+ con la bandera --env-file:

node --env-file=.env build/index.js

Alternativa (usando variables de entorno directamente):

export STRAPI_URL=http://localhost:1337
export STRAPI_ADMIN_EMAIL=your_admin_email@example.com
export STRAPI_ADMIN_PASSWORD=your_admin_password
# export STRAPI_API_TOKEN=your-api-token # Optional fallback
export STRAPI_DEV_MODE=true # optional
 
# Run the globally installed package (if installed via npm install -g)
strapi-mcp 
# Or run the local build directly
node build/index.js

Características

  • Listar y leer tipos de contenido
  • Obtener, crear, actualizar y eliminar entradas
  • Subir archivos multimedia
  • Conectar y desconectar relaciones
  • Obtener esquemas de tipos de contenido

Registro de cambios

0.2.3 - 2025-07-25

  • CORRECCIÓN CRÍTICA: Se corrigió el problema de tiempo de espera en las herramientas de relación - connect_relation y disconnect_relation ahora manejan correctamente los errores de validación en lugar de agotar el tiempo de espera
  • MANEJO DE ERRORES MEJORADO: Todos los errores de validación ahora devuelven mensajes de error adecuados en lugar de causar tiempos de espera en las herramientas

0.2.2 - 2025-07-25

  • HERRAMIENTAS DE RELACIÓN MEJORADAS: Se mejoró el manejo de errores para connect_relation y disconnect_relation con mensajes detallados de validación y solución de problemas
  • CREATE_COMPONENT CORREGIDO: Se corrigió el error de validación de parámetros - ahora valida correctamente los parámetros individuales en lugar de un solo objeto
  • MEJOR DIAGNÓSTICO DE ERRORES: Se agregaron mensajes de error específicos para campos de relación inválidos, entradas inexistentes e IDs malformados
  • Las 20 herramientas ahora funcionan al 100% con manejo robusto de errores y validación

0.2.0 - 2025-07-25

  • CORRECCIÓN DE ERROR CRÍTICO: Se corrigió validateStrapiConnection que causaba el error "undefined response status"
  • PROBLEMA DE CONEXIÓN MCP RESUELTO: Se corrigió el problema de "luz verde pero no funciona" con las herramientas de IA
  • MANEJO DE ERRORES MEJORADO: Mejor lógica de validación de conexión con manejo adecuado de autenticación de administrador
  • Los usuarios deben actualizar a esta versión si experimentan problemas de conexión MCP con herramientas de IA

0.1.9 - 2025-07-02

  • CORRECCIÓN DE DESBORDAMIENTO DE VENTANA DE CONTEXTO: Se agregaron límites de tamaño y filtrado de respuestas para evitar que los archivos base64 abrumen la ventana de contexto
  • NUEVA HERRAMIENTA: Se agregó upload_media_from_path - Sube archivos desde rutas de archivo locales (máx. 10MB) para evitar problemas de contexto base64
  • UPLOAD_MEDIA MEJORADO: Se agregó límite de tamaño base64 de 1MB (~archivo de 750KB) con mensajes de error claros sobre desbordamiento de contexto
  • REGISTRO MEJORADO: Datos base64 truncados en registros para prevenir spam de registros y desbordamiento de contexto
  • FILTRADO DE RESPUESTAS: Filtra automáticamente cadenas base64 grandes de las respuestas de API para prevenir desbordamiento de eco

0.1.8 - 2025-06-12

  • CORRECCIÓN DE ERROR MAYOR: Se reemplazaron fallos silenciosos con mensajes de error descriptivos cuando no se pueden obtener tipos de contenido o entradas
  • Validación de configuración agregada: Detecta tokens de API de marcador de posición y sale con mensajes de error útiles
  • Validación de conexión agregada: Prueba la conectividad de Strapi antes de intentar operaciones con diagnósticos de error específicos
  • Manejo de errores mejorado: Diagnósticos de error completos que distinguen entre colecciones vacías legítimas y errores reales
  • Solución de problemas mejorada: Todos los mensajes de error incluyen pasos específicos para resolver problemas comunes de configuración

0.1.7 - 2025-05-17

  • Se agregaron herramientas publish_entry y unpublish_entry: Gestión completa del ciclo de vida del contenido
  • Gestión de componentes agregada: list_components, get_component_schema, create_component, update_component
  • Se agregó la herramienta delete_content_type: Elimina tipos de contenido existentes a través de la API del Constructor de Tipos de Contenido
  • Autenticación de administrador mejorada: Mejor manejo de errores y gestión de tokens para todas las operaciones de API

0.1.6

  • Se agregó la herramienta create_content_type: Permite crear nuevos tipos de contenido a través de la API del Constructor de Tipos de Contenido (requiere credenciales de administrador).
  • Credenciales de administrador priorizadas: Lógica actualizada para preferir correo/contraseña de administrador para obtener tipos de contenido y esquemas, mejorando la confiabilidad.
  • Documentación actualizada: Se aclararon los métodos de autenticación y los procedimientos de ejecución recomendados.

0.1.5

  • Descubrimiento de tipos de contenido mejorado con múltiples métodos de respaldo
  • Se agregó manejo de errores y registro más robustos
  • Inferencia de esquema mejorada para tipos de contenido

0.1.4

  • Manejo de errores mejorado con códigos de error más específicos
  • Se agregaron códigos de error ResourceNotFound y AccessDenied
  • Mejores mensajes de error para errores comunes de API

0.1.3

  • Lanzamiento público inicial

Licencia

MIT

Servidor MCP strapi-mcp

Un servidor MCP para tu Strapi CMS

Este es un servidor MCP basado en TypeScript que se integra con Strapi CMS. Proporciona acceso a los tipos de contenido y entradas de Strapi a través del protocolo MCP, permitiéndote:

  • Acceder a los tipos de contenido de Strapi como recursos
  • Crear, leer, actualizar y eliminar entradas de contenido
  • Gestionar tu contenido de Strapi a través de herramientas MCP

Características

Recursos

  • Listar y acceder a tipos de contenido a través de URIs strapi://content-type/
  • Cada tipo de contenido expone sus entradas como JSON
  • Tipo MIME Application/JSON para acceso a contenido estructurado

Herramientas

  • list_content_types - Lista todos los tipos de contenido disponibles en Strapi
  • get_entries - Obtiene entradas para un tipo de contenido específico con filtrado, paginación, ordenamiento y población de relaciones opcionales
  • get_entry - Obtiene una entrada específica por ID
  • create_entry - Crea una nueva entrada para un tipo de contenido
  • update_entry - Actualiza una entrada existente
  • delete_entry - Elimina una entrada
  • upload_media - Sube un archivo multimedia a Strapi (máx. ~750KB de archivo debido a límites de contexto base64)
  • upload_media_from_path - Sube un archivo multimedia desde una ruta de archivo local (máx. 10MB, evita desbordamiento de contexto)
  • get_content_type_schema - Obtiene el esquema (campos, tipos, relaciones) para un tipo de contenido específico.
  • connect_relation - Conecta entradas relacionadas al campo de relación de una entrada.
  • disconnect_relation - Desconecta entradas relacionadas del campo de relación de una entrada.
  • create_content_type - Crea un nuevo tipo de contenido usando la API del Constructor de Tipos de Contenido (Requiere privilegios de Administrador).
  • publish_entry - Publica una entrada específica.
  • unpublish_entry - Despublica una entrada específica.
  • list_components - Lista todos los componentes disponibles en Strapi.
  • get_component_schema - Obtiene el esquema para un componente específico.
  • create_component - Crea un nuevo componente.
  • update_component - Actualiza un componente existente.

Características Avanzadas

Filtrado, Paginación y Ordenamiento

La herramienta get_entries admite opciones de consulta avanzadas:

{
  "contentType": "api::article.article",
  "filters": {
    "title": {
      "$contains": "hello"
    }
  },
  "pagination": {
    "page": 1,
    "pageSize": 10
  },
  "sort": ["title:asc", "createdAt:desc"],
  "populate": ["author", "categories"]
}

URIs de Recursos

Se puede acceder a los recursos con varios formatos de URI:

  • strapi://content-type/api::article.article - Obtener todos los artículos
  • strapi://content-type/api::article.article/1 - Obtener artículo con ID 1
  • strapi://content-type/api::article.article?filters={"title":{"$contains":"hello"}} - Obtener artículos filtrados

Publicación y Despublicación de Contenido

Las herramientas publish_entry y unpublish_entry proporcionan control sobre el ciclo de vida del contenido:

{
  "contentType": "api::article.article",
  "id": "1"
}

Estas herramientas utilizan las rutas de API de administración para acciones de publicación/despublicación, con un respaldo para actualizar directamente el campo publishedAt si no hay permisos de administrador disponibles.

Gestión de Componentes

Los componentes de Strapi se pueden gestionar con las siguientes herramientas:

  • list_components: Obtener todos los componentes disponibles
  • get_component_schema: Ver la estructura de un componente específico
  • create_component: Crear un nuevo componente con campos especificados
  • update_component: Modificar un componente existente

Ejemplo de creación de un componente:

{
  "componentData": {
    "displayName": "Security Settings",
    "category": "security",
    "icon": "shield",
    "attributes": {
      "enableTwoFactor": {
        "type": "boolean", 
        "default": false
      },
      "passwordExpiration": {
        "type": "integer",
        "min": 0
      }
    }
  }
}

Desarrollo

Instalar dependencias:

npm install

Compilar el servidor:

npm run build

Para desarrollo con reconstrucción automática:

npm run watch

Instalación

Para instrucciones detalladas paso a paso sobre cómo implementar y probar este servidor MCP, consulta el archivo DEPLOYMENT.md.

Configuración rápida:

  1. Compila el servidor: npm run build
  2. Configura tu instancia de Strapi y obtén un token de API
  3. Agrega la configuración del servidor a Claude Desktop:

En MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json En Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "strapi-mcp": {
      "command": "npx",
      "args": ["strapi-mcp"],
      "env": {
        "STRAPI_URL": "http://localhost:1337",
        "STRAPI_ADMIN_EMAIL": "your_admin_email@example.com",
        "STRAPI_ADMIN_PASSWORD": "your_admin_password"
      }
    }
  }
}

Si instalaste desde el código fuente, usa la ruta directa:

{
  "mcpServers": {
    "strapi-mcp": {
      "command": "/path/to/strapi-mcp/build/index.js",
      "env": {
        "STRAPI_URL": "http://localhost:1337",
        "STRAPI_ADMIN_EMAIL": "your_admin_email@example.com",
        "STRAPI_ADMIN_PASSWORD": "your_admin_password"
      }
    }
  }
}

Variables de Entorno

  • STRAPI_URL (opcional): La URL de tu instancia de Strapi (por defecto es http://localhost:1337)
  • STRAPI_ADMIN_EMAIL y STRAPI_ADMIN_PASSWORD (Recomendado): Credenciales para un usuario administrador de Strapi. Requeridas para funcionalidad completa como obtener esquemas de tipos de contenido.
  • STRAPI_API_TOKEN (Respaldo opcional): Tu token de API de Strapi. Se puede usar si no se proporcionan credenciales de administrador, pero la funcionalidad podría estar limitada según los permisos del token.
  • STRAPI_DEV_MODE (opcional): Establécelo en "true" para habilitar funciones de modo de desarrollo (por defecto es false)

Prioridad de Autenticación

El servidor prioriza los métodos de autenticación en este orden:

  1. Correo y Contraseña de Administrador (STRAPI_ADMIN_EMAIL, STRAPI_ADMIN_PASSWORD)
  2. Token de API (STRAPI_API_TOKEN)

Se recomienda encarecidamente usar Credenciales de Administrador para obtener los mejores resultados.

Cómo Obtener Credenciales de Strapi

  • Credenciales de Administrador: Usa el correo y la contraseña de un Súper Administrador existente o crea un usuario administrador dedicado en tu panel de administración de Strapi (Configuración > Panel de Administración > Usuarios).
  • Token de API: (Respaldo opcional)
  1. Inicia sesión en tu panel de administración de Strapi
  2. Ve a Configuración > Tokens de API
  3. Haz clic en "Crear nuevo Token de API"
  4. Establece un nombre, descripción y tipo de token (preferiblemente "Acceso completo")
  5. Copia el token generado y úsalo en la configuración de tu servidor MCP

Solución de Problemas

Problemas Comunes y Soluciones:

1. Error de Token de API de Marcador de Posición

[Error] STRAPI_API_TOKEN appears to be a placeholder value...

Solución: Reemplaza "strapi_token" o "your-api-token-here" con un token de API real de tu panel de administración de Strapi.

2. Error de Conexión Rechazada

Cannot connect to Strapi instance: Connection refused. Is Strapi running at http://localhost:1337?

Solución:

  • Asegúrate de que Strapi esté ejecutándose: npm run develop o yarn develop
  • Verifica que la URL en STRAPI_URL sea correcta
  • Verifica que tu base de datos (MySQL/PostgreSQL) esté ejecutándose

3. Autenticación Fallida

Cannot connect to Strapi instance: Authentication failed. Check your API token or admin credentials.

Solución:

  • Verifica que tu token de API tenga los permisos adecuados (preferiblemente "Acceso completo")
  • Comprueba que el correo/contraseña de administrador sean correctos
  • Asegúrate de que el usuario administrador exista y esté activo

4. Desbordamiento de Ventana de Contexto con Subidas de Archivos

Error: Context window overflow due to large base64 strings

Problema: Los archivos codificados en base64 pueden ser extremadamente grandes (incluso imágenes pequeñas pueden ser 50-100KB de texto), causando desbordamiento de la ventana de contexto. Soluciones:

  • Usa upload_media_from_path en lugar de upload_media para archivos mayores de ~500KB
  • Reduce el tamaño de los archivos antes de subirlos (comprime imágenes, reduce la resolución)
  • Usa archivos más pequeños: la herramienta upload_media tiene un límite de 1MB en base64 (~750KB por archivo)

5. Tipos de contenido falsos (api::data.data, api::error.error)

Este problema se ha corregido en v0.1.8. Si aún los ves, es posible que estés usando una versión anterior.

6. Resultados vacíos vs errores

A partir de v0.1.8, el servidor ahora distingue claramente entre:

  • Colecciones vacías (el tipo de contenido existe pero no tiene entradas) → Devuelve {"data": [], "meta": {...}}
  • Errores reales (el tipo de contenido no existe, fallo de autenticación, etc.) → Lanza un error descriptivo con pasos de solución de problemas

7. Errores de permisos

Access forbidden. Your API token may lack necessary permissions.

Solución:

  • Usa credenciales de administrador en lugar de un token de API para obtener toda la funcionalidad
  • Si usas un token de API, asegúrate de que tenga permisos de "Acceso completo"
  • Comprueba que el tipo de contenido permita acceso público si usas un token de API limitado

Depuración

Dado que los servidores MCP se comunican a través de stdio, la depuración puede ser un desafío. Recomendamos usar el MCP Inspector, que está disponible como script del paquete:

npm run inspector

El Inspector proporcionará una URL para acceder a las herramientas de depuración en tu navegador.

Ejemplos de uso

Una vez que el servidor MCP esté configurado y en ejecución, puedes usarlo con Claude para interactuar con tu CMS de Strapi. Aquí tienes algunos ejemplos:

Listado de tipos de contenido

use_mcp_tool(
  server_name: "strapi-mcp",
  tool_name: "list_content_types",
  arguments: {}
)

Obtención de entradas

use_mcp_tool(
  server_name: "strapi-mcp",
  tool_name: "get_entries",
  arguments: {
    "contentType": "api::article.article",
    "filters": {
      "title": {
        "$contains": "hello"
      }
    },
    "pagination": {
      "page": 1,
      "pageSize": 10
    },
    "sort": ["title:asc"]
  }
)

Creación de una entrada

use_mcp_tool(
  server_name: "strapi-mcp",
  tool_name: "create_entry",
  arguments: {
    "contentType": "api::article.article",
    "data": {
      "title": "My New Article",
      "content": "This is the content of my article.",
      "publishedAt": "2023-01-01T00:00:00.000Z"
    }
  }
)

Subida de medios

Método 1: Subida en base64 (solo archivos pequeños)

use_mcp_tool(
  server_name: "strapi-mcp",
  tool_name: "upload_media",
  arguments: {
    "fileData": "base64-encoded-data-here",
    "fileName": "image.jpg",
    "fileType": "image/jpeg"
  }
)

Método 2: Subida por ruta de archivo (recomendado para archivos más grandes)

use_mcp_tool(
  server_name: "strapi-mcp",
  tool_name: "upload_media_from_path",
  arguments: {
    "filePath": "/path/to/your/image.jpg"
  }
)

Conexión de relaciones

use_mcp_tool(
  server_name: "strapi-mcp",
  tool_name: "connect_relation",
  arguments: {
    "contentType": "api::article.article",
    "id": "1",
    "relationField": "authors",
    "relatedIds": [2, 3]
  }
)

Desconexión de relaciones

use_mcp_tool(
  server_name: "strapi-mcp",
  tool_name: "disconnect_relation",
  arguments: {
    "contentType": "api::article.article",
    "id": "1",
    "relationField": "authors",
    "relatedIds": [3]
  }
 )

Creación de un tipo de contenido

use_mcp_tool(
  server_name: "strapi-mcp-local",
  tool_name: "create_content_type",
  arguments: {
    "displayName": "My New Product",
    "singularName": "product",
    "pluralName": "products",
    "kind": "collectionType",
    "description": "Represents products in the store",
    "draftAndPublish": true,
    "attributes": {
      "name": { "type": "string", "required": true },
      "description": { "type": "text" },
      "price": { "type": "decimal", "required": true },
      "stock": { "type": "integer" }
    }
  }
)

Actualización de un tipo de contenido

use_mcp_tool(
  server_name: "strapi-mcp-local",
  tool_name: "update_content_type",
  arguments: {
    "contentType": "api::speaker.speaker",
    "attributes": {
      "isHighlightSpeaker": {
        "type": "boolean",
        "default": false
      },
      "newTextField": {
        "type": "string"
      }
    }
  }
)

Acceso a recursos