# 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
```bash
# 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
```bash
# 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:
```json
{
"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:
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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
```json
{
"contentType": "products",
"data": {
"name": "Producto Ejemplo",
"price": 99.99,
"stock": 100,
"category": 1
}
}
```
### Perfiles de Usuario
```json
{
"contentType": "profiles",
"data": {
"displayName": "Juan Pérez",
"bio": "Desarrollador",
"avatar": "https://example.com/avatar.jpg"
}
}
```
## 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
| Variable | Descripción | Valor por defecto |
|----------|-------------|-------------------|
| `STRAPI_URL` | URL base de la API de Strapi | `http://localhost:1337` |
| `NODE_ENV` | Entorno de ejecución | `production` |
## Debugging
Los logs se escriben a `stderr` para no interferir con el protocolo MCP (que usa `stdout`):
```bash
# 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:
```bash
node --version # Debe mostrar v22.x.x o superior
```
### Error de conexión a Strapi
Verifica que Strapi esté corriendo y accesible:
```bash
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.
