MCP Strapi Server

MCP Strapi Server

Un servidor Model Context Protocol (MCP) para operaciones CRUD en Strapi, permitiendo interactuar con cualquier content type de Strapi a través de herramientas estandarizadas.

Características

• ✅ 13 Herramientas para operaciones CRUD, gestión de contenidos y medios
• ✅ Sistema genérico - funciona con cualquier content type
• ✅ Fetch nativo - sin dependencias adicionales (Node.js 22+)
• ✅ Stdio transport - integración local con Claude Desktop
• ✅ TypeScript moderno - tipado completo y seguro
• ✅ Gestión de medios - búsqueda, obtención y carga de archivos
• ✅ i18n support - soporte completo para internacionalización

Requisitos

• Node.js 22+ (para soporte nativo de fetch)
• Strapi corriendo en localhost:1337 (o configurado en STRAPI_URL)

Instalación

Opción 1: Desarrollo Local

# Instalar dependencias
npm install

# Copiar variables de entorno
cp .env.example .env

# Editar .env con tu configuración de Strapi
nano .env

# Compilar TypeScript
npm run build

# Ejecutar servidor
npm start

Opción 2: Desarrollo con Watch Mode

# Ejecutar con hot-reload (usando tsx)
npm run dev

Configuración en Claude Desktop

Añade el servidor MCP a tu configuración de Claude Desktop:

{
  "mcpServers": {
    "strapi": {
      "command": "node",
      "args": ["/ruta/absoluta/a/mcp-strapi/dist/index.js"],
      "env": {
        "STRAPI_URL": "http://localhost:1337",
        "STRAPI_API_TOKEN": "tu-token-opcional"
      }
    }
  }
}

⚠️ Notas Importantes sobre Content Types

Uso del parámetro contentType

Para las operaciones CRUD (create, read, list, update, delete), SIEMPRE debes usar el nombre PLURAL del content type:

✅ CORRECTO:

• "products"
• "articles"
• "categories"
• "profiles"

❌ INCORRECTO:

• "api::product.product" (UID completo)
• "product" (singular)
• "Product" (capitalizado)

Cómo obtener el nombre correcto

1. Usa la herramienta strapi-list-content-types para ver todos los content types disponibles
2. En la respuesta, busca el campo pluralName - ese es el valor que debes usar
3. Ejemplo de respuesta:

{
  "uid": "api::product.product",
  "apiID": "product",
  "pluralName": "products"  // ← Usa este valor
}

Excepciones

La herramienta strapi-add-field es la ÚNICA que requiere el UID completo:

• ✅ "api::product.product" para strapi-add-field
• ❌ "products" NO funciona con strapi-add-field

Herramientas Disponibles (13 total)

CRUD Operations (6 tools)

1. strapi-create

Crea una nueva entrada en un content type.

Parámetros:

• contentType (string): Nombre PLURAL del content type (ej: "articles", "products")
• data (object): Datos de la entrada
• populate (string[], opcional): Relaciones a poblar

Ejemplo:

{
  "contentType": "articles",
  "data": {
    "title": "Mi Artículo",
    "content": "Contenido del artículo",
    "publishedAt": null
  },
  "populate": ["author", "category"]
}

⚠️ IMPORTANTE: Usa el nombre plural del content type ("articles"), NO el UID completo ("api::article.article").

2. strapi-read

Lee una entrada específica por ID o documentId.

Parámetros:

• contentType (string): Nombre PLURAL del content type (ej: "articles")
• id (string | number): ID numérico o documentId (string) de la entrada
• fields (string[], opcional): Campos a retornar
• populate (string[], opcional): Relaciones a poblar

Ejemplo:

{
  "contentType": "articles",
  "id": "abc123xyz",
  "fields": ["title", "content"],
  "populate": ["author"]
}

💡 Nota: En Strapi v5, el parámetro id acepta tanto IDs numéricos como documentIds (strings).

3. strapi-list

Lista entradas con filtrado, paginación y ordenamiento.

Parámetros:

• contentType (string): Nombre PLURAL del content type (ej: "articles")
• filters (object, opcional): Filtros de búsqueda
• sort (string[], opcional): Campos de ordenamiento
• pagination (object, opcional): Configuración de paginación
• fields (string[], opcional): Campos a retornar
• populate (string[], opcional): Relaciones a poblar

Ejemplo:

{
  "contentType": "articles",
  "filters": {
    "publishedAt": { "$notNull": true }
  },
  "sort": ["createdAt:desc"],
  "pagination": {
    "page": 1,
    "pageSize": 10
  },
  "populate": ["author", "category"]
}

4. strapi-update

Actualiza una entrada existente (actualización parcial).

Parámetros:

• contentType (string): Nombre PLURAL del content type (ej: "articles")
• id (string | number): ID numérico o documentId (string) de la entrada
• data (object): Datos a actualizar (solo los campos que quieres cambiar)
• populate (string[], opcional): Relaciones a poblar

Ejemplo:

{
  "contentType": "articles",
  "id": "abc123xyz",
  "data": {
    "title": "Título Actualizado",
    "publishedAt": "2024-01-15T10:00:00.000Z"
  }
}

5. strapi-delete

Elimina una entrada.

Parámetros:

• contentType (string): Nombre PLURAL del content type (ej: "articles")
• id (string | number): ID numérico o documentId (string) de la entrada a eliminar

Ejemplo:

{
  "contentType": "articles",
  "id": "abc123xyz"
}

⚠️ Nota: Puede aparecer un error de "JSON input" después de eliminar, pero la entrada SÍ se elimina correctamente. Esto ocurre porque Strapi retorna una respuesta vacía.

Content Type Management (3 tools)

• strapi-list-content-types - Listar todos los content types disponibles
• strapi-get-schema - Obtener schema detallado de un content type
• strapi-add-field - Añadir campo a un content type

Internationalization (1 tool)

• strapi-get-i18n-locales - Obtener locales disponibles

Media Management (3 tools)

• strapi-search-media - Buscar archivos en la biblioteca de medios
• strapi-get-media - Obtener archivo específico por ID
• strapi-upload-media - Subir archivo a la biblioteca de medios

Ejemplos de Uso con Content Types Personalizados

Productos

{
  "contentType": "products",
  "data": {
    "name": "Producto Ejemplo",
    "price": 99.99,
    "stock": 100,
    "category": 1
  }
}

Perfiles de Usuario

{
  "contentType": "profiles",
  "data": {
    "displayName": "Juan Pérez",
    "bio": "Desarrollador",
    "avatar": ""
  }
}

Estructura del Proyecto

mcp-strapi/
├── docs/                        # Documentación
├── src/
│   ├── index.ts                 # Entry point
│   ├── server.ts                # Configuración MCP server
│   ├── tools/                   # Herramientas (13 total)
│   │   ├── create.ts
│   │   ├── create-with-locales.ts
│   │   ├── read.ts
│   │   ├── list.ts
│   │   ├── update.ts
│   │   ├── delete.ts
│   │   ├── list-content-types.ts
│   │   ├── get-schema.ts
│   │   ├── add-field.ts
│   │   ├── get-i18n-locales.ts
│   │   ├── search-media.ts
│   │   ├── get-media.ts
│   │   └── upload-media.ts
│   ├── services/
│   │   ├── strapi-client.ts    # Cliente HTTP (fetch nativo)
│   │   └── i18n-validator.ts   # Validador de internacionalización
│   ├── types/
│   │   └── index.ts            # Tipos TypeScript
│   └── config/
│       └── environment.ts      # Variables de entorno
├── package.json
├── tsconfig.json
├── CLAUDE.md
└── README.md

Variables de Entorno

Debugging

Los logs se escriben a stderr para no interferir con el protocolo MCP (que usa stdout):

# Ver logs en desarrollo
npm run dev 2>&1 | grep "ERROR\|CONFIG\|TOOL"

Características implementadas

• ✅ Autenticación con API Tokens de Strapi
• ✅ Validación de i18n con detección de idiomas heredados
• ✅ 13 herramientas completas (CRUD, Content Types, Medios, i18n)
• ✅ Soporte para localizaciones múltiples
• ✅ Gestión completa de medios (búsqueda, descarga, carga)
• ✅ Documentación exhaustiva en CLAUDE.md
• ✅ Strict mode para validaciones de contenido

Solución de Problemas

Error: "Node.js 22+ required"

Asegúrate de tener Node.js 22 o superior instalado:

node --version  # Debe mostrar v22.x.x o superior

Error de conexión a Strapi

Verifica que Strapi esté corriendo y accesible:

curl http://localhost:1337/api

Licencia

MIT

Contribuciones

Las contribuciones son bienvenidas. Por favor:

1. Fork el repositorio
2. Crea una rama para tu feature (git checkout -b feature/amazing-feature)
3. Commit tus cambios (git commit -m 'Add amazing feature')
4. Push a la rama (git push origin feature/amazing-feature)
5. Abre un Pull Request

Autor

Creado con las mejores prácticas de MCP TypeScript SDK y Strapi Entity Service API.