Squidex MCP server

Servidor MCP para gestionar contenido y esquemas de Squidex CMS desde agentes de IA.

Documentación

squidex-mcp (no oficial)

Un servidor MCP (Model Context Protocol) que permite a los agentes de IA leer y escribir contenido CMS de Squidex directamente. MCP es un protocolo abierto e independiente del modelo: cualquier cliente compatible funciona (Claude Code, Claude Desktop, Cursor, Windsurf, agentes personalizados en cualquier modelo), no solo los de Anthropic. Construido sobre Bun para un inicio rápido y sin dependencias: cada sesión de agente genera su propio proceso de servidor a través de stdio.

Lo que puede hacer

Herramienta	Propósito
`schema_list`	Listar esquemas de contenido en la aplicación
`schema_get`	Obtener los campos de un esquema, incluidos los IDs de campo y el modo de localización
`schema_create`	Crear un nuevo esquema de contenido
`schema_add_field`	Añadir un campo a un esquema (incluidos campos anidados Array/Component)
`schema_update_field`	Reemplazar las propiedades de un campo
`schema_publish`	Publicar un esquema para que se pueda crear contenido sobre él
`schema_delete`	Eliminar un esquema — para descartar una iteración de diseño fallida
`content_query`	Consultar elementos de contenido (estilo OData `filter`/`top`/`skip`/`orderby`/`search`)
`content_get`	Obtener un solo elemento de contenido
`content_create`	Crear un elemento de contenido
`content_update`	Reemplazar los datos de un elemento de contenido
`content_delete`	Eliminar un elemento de contenido
`content_change_status`	Cambiar el estado del flujo de trabajo (Borrador/Publicado/Archivado)
`asset_list`	Listar/consultar la biblioteca de activos
`asset_get`	Obtener los metadatos de un solo activo por ID
`asset_upload`	Subir un nuevo activo desde un archivo local o una URL remota
`language_list`	Listar los idiomas configurados de la aplicación, para particionar campos localizados
`profile_list`	Listar los perfiles de Squidex configurados (sin secretos)

Puede apuntar a múltiples aplicaciones/instancias de Squidex (por ejemplo, prod + staging) desde un solo servidor en ejecución: cada herramienta acepta un parámetro opcional profile, conmutable sin reiniciar el servidor. Ver Perfiles a continuación.

Inicio rápido (sin necesidad de programar)

La forma más fácil de ejecutarlo es mediante npx — sin descargas, sin pasos de compilación, solo una instalación de Node.js (que la mayoría de las máquinas ya tienen).

1. Obtén tus credenciales de Squidex

En tu aplicación de Squidex: Configuración → Clientes → crea (o copia) un cliente. Necesitas:

tu URL de Squidex (por ejemplo, https://cloud.squidex.io)
el nombre de tu aplicación
el ID de cliente (parece your-app-name:default)
el secreto de cliente

2. Registra el servidor con tu cliente MCP

Claude Code:

claude mcp add \
  --env SQUIDEX_URL=https://cloud.squidex.io \
  --env SQUIDEX_APP=your-app-name \
  --env SQUIDEX_CLIENT_ID=your-app-name:default \
  --env SQUIDEX_CLIENT_SECRET=your-client-secret \
  --transport stdio squidex \
  --scope user \
  -- npx -y @shalotts/squidex-mcp

--scope user lo hace disponible en todos los proyectos, no solo en el actual. -y evita que npx se detenga en un mensaje interactivo de "¿ok para instalar?", que de otro modo colgaría la conexión en la primera ejecución.

Claude Desktop: edita el archivo de configuración propio de Claude Desktop para tu sistema operativo (esta es la configuración del lanzador de Claude Desktop, no squidex.config.json de Perfiles a continuación — el bloque env aquí solo establece variables de entorno para el proceso que Claude Desktop inicia) — macOS: ~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json · Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "squidex": {
      "command": "npx",
      "args": ["-y", "@shalotts/squidex-mcp"],
      "env": {
        "SQUIDEX_URL": "https://cloud.squidex.io",
        "SQUIDEX_APP": "your-app-name",
        "SQUIDEX_CLIENT_ID": "your-app-name:default",
        "SQUIDEX_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Reinicia el cliente después de editar.

3. Pruébalo

Pregunta a tu asistente algo como "Lista los esquemas de contenido en mi aplicación de Squidex". Si responde con tus esquemas, está funcionando.

Alternativa: binario independiente (sin necesidad de Node.js)

Si Node.js/npx no está disponible, descarga un binario precompilado desde la página de Releases en su lugar:

SO	Archivo
Linux (x64)	`squidex-mcp-linux-x64`
Linux (ARM64)	`squidex-mcp-linux-arm64`
macOS (Intel)	`squidex-mcp-darwin-x64`
macOS (Apple Silicon)	`squidex-mcp-darwin-arm64`
Windows (x64)	`squidex-mcp-windows-x64.exe`

Hazlo ejecutable en macOS/Linux (chmod +x ~/Downloads/squidex-mcp-<your-platform>; macOS también puede requerir xattr -d com.apple.quarantine <file> ya que no está notarizado), luego usa su ruta absoluta como command en lugar de npx en la configuración anterior (y elimina las partes args/-y, que son específicas de npx).

Perfiles (múltiples instancias de Squidex)

Si necesitas más de una aplicación/instancia de Squidex (por ejemplo, prod + staging) accesible desde el mismo servidor, usa un archivo squidex.config.json en lugar de variables de entorno:

{
  "defaultProfile": "prod",
  "requestTimeoutMs": 15000,
  "profiles": {
    "prod":    { "url": "https://cloud.squidex.io", "app": "blog",  "clientId": "...", "clientSecret": "..." },
    "staging": { "url": "https://cloud.squidex.io", "app": "blog-s", "clientId": "...", "clientSecret": "..." }
  }
}

Cada herramienta acepta un parámetro opcional profile para elegir qué destino usar — no se necesita reiniciar el servidor para cambiar. El archivo se vuelve a leer en cada llamada. requestTimeoutMs (por defecto 15000) se aplica a cada solicitud HTTP de Squidex en todos los perfiles.

Por defecto, el servidor busca squidex.config.json en su directorio de trabajo actual; apunta a otro lugar con la variable de entorno SQUIDEX_MCP_CONFIG (se recomienda ruta absoluta, ya que el directorio de trabajo del proceso cliente no siempre es predecible). Si no se encuentra ningún archivo de configuración, las cuatro variables de entorno SQUIDEX_* del inicio rápido se usan como un único perfil implícito default.

Los datos de los campos de contenido ya deben estar formateados según la partición de Squidex ({ "title": { "iv": "..." } } para campos invariantes, { "en": "...", "de": "..." } para localizados) — llama a schema_get primero para ver el modo de cada campo, y a language_list para ver qué códigos de idioma están realmente configurados en la aplicación.

Desarrollo

bun install
bun test               # unit tests (config, token cache, query builder — no live Squidex needed)
bun run typecheck       # tsc --noEmit
bun run dev             # start the server with --watch, for local development

Apunta tu cliente MCP a bun run src/index.ts en este directorio en lugar de un binario descargado mientras desarrollas.

bun run build produce el dist/index.js orientado a Node que se publica en npm (las dependencias permanecen externas — se instalan normalmente vía npm/npx, no empaquetadas). Por separado, bun run build:binary compila un binario independiente solo para tu SO actual (dist/squidex-mcp); bun run build:binary:all compila de forma cruzada los cinco objetivos de lanzamiento a la vez (dist/squidex-mcp-<platform>) — el mismo comando release.yml se ejecuta cuando se empuja una etiqueta.

Squidex local para pruebas de extremo a extremo

docker-compose.yml ejecuta un Squidex local + MongoDB para pruebas reales (no simuladas):

docker compose up -d                    # starts Squidex on http://localhost:8085
bun run scripts/e2e-bootstrap.ts        # creates a "mcp-test" app + "posts" schema, writes squidex.config.json
bun run scripts/smoke.ts                # or drive the tools directly via an MCP client

e2e-bootstrap.ts es idempotente — seguro de volver a ejecutar contra una instancia ya inicializada. Se autentica como el cliente superadmin root (creado vía IDENTITY__ADMINCLIENTID/IDENTITY__ADMINCLIENTSECRET en docker-compose.yml, credenciales solo de desarrollo, no secretos reales) y escribe un perfil local en squidex.config.json.

docker compose down lo detiene; agrega -v para también borrar el volumen de Mongo (Squidex fresco en el próximo up).

Lanzamiento

Empujar una etiqueta que coincida con v*.*.* activa .github/workflows/release.yml: ejecuta la suite de pruebas, publica el paquete en npm, compila de forma cruzada binarios independientes para Linux/macOS/Windows y los adjunta a un Release de GitHub.

git tag v0.2.0
git push origin v0.2.0

Publicar en npm usa Trusted Publishing (OIDC) — no se necesita token/secreto. Configuración única: publica la primera versión manualmente (npm login && npm publish --access public, ya que la configuración de Trusted Publisher requiere que el paquete ya exista), luego en la configuración de npmjs.com del paquete agrega un Trusted Publisher que apunte a este repositorio (francyfox/squidex-mcp) y al archivo de flujo de trabajo (release.yml). Después de eso, cada empuje de etiqueta publica automáticamente.