Squidex MCP server

Servidor MCP para gerenciar conteúdo e esquemas do Squidex CMS a partir de agentes de IA

Documentação

squidex-mcp (não oficial)

Um servidor MCP (Model Context Protocol) que permite que agentes de IA leiam e escrevam conteúdo CMS do Squidex diretamente. MCP é um protocolo aberto e agnóstico de modelo — qualquer cliente compatível funciona (Claude Code, Claude Desktop, Cursor, Windsurf, agentes personalizados em qualquer modelo), não apenas o da Anthropic. Construído em Bun para inicialização rápida e sem dependências — cada sessão de agente inicia seu próprio processo de servidor via stdio.

O que ele pode fazer

Ferramenta	Finalidade
`schema_list`	Listar esquemas de conteúdo no aplicativo
`schema_get`	Obter os campos de um esquema, incluindo IDs de campo e modo de localização
`schema_create`	Criar um novo esquema de conteúdo
`schema_add_field`	Adicionar um campo a um esquema (incluindo campos aninhados Array/Component)
`schema_update_field`	Substituir as propriedades de um campo
`schema_publish`	Publicar um esquema para que conteúdo possa ser criado nele
`schema_delete`	Excluir um esquema — para descartar uma iteração de design com falha
`content_query`	Consultar itens de conteúdo (estilo OData `filter`/`top`/`skip`/`orderby`/`search`)
`content_get`	Obter um único item de conteúdo
`content_create`	Criar um item de conteúdo
`content_update`	Substituir os dados de um item de conteúdo
`content_delete`	Excluir um item de conteúdo
`content_change_status`	Alterar o status do fluxo de trabalho (Rascunho/Publicado/Arquivado)
`asset_list`	Listar/consultar a biblioteca de ativos
`asset_get`	Obter os metadados de um único ativo por ID
`asset_upload`	Enviar um novo ativo de um arquivo local ou de uma URL remota
`language_list`	Listar os idiomas configurados do aplicativo, para particionar campos localizados
`profile_list`	Listar os perfis Squidex configurados (sem segredos)

Ele pode atingir vários aplicativos/instâncias Squidex (ex.: produção + homologação) a partir de um único servidor em execução — toda ferramenta aceita um parâmetro opcional profile, alternável sem reiniciar o servidor. Veja Perfis abaixo.

Início rápido (sem necessidade de codificação)

A maneira mais fácil de executá-lo é via npx — sem download, sem etapa de build, apenas uma instalação Node.js (que a maioria das máquinas já tem).

1. Obtenha suas credenciais do Squidex

No seu aplicativo Squidex: Configurações → Clientes → crie (ou copie) um cliente. Você precisa de:

sua URL do Squidex (ex.: https://cloud.squidex.io)
o nome do seu aplicativo
o ID do cliente (parece your-app-name:default)
o segredo do cliente

2. Registre o servidor no seu 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 o torna disponível em todos os projetos, não apenas no atual. -y impede que o npx pause em um prompt interativo "ok para instalar?", o que penduraria a conexão na primeira execução.

Claude Desktop: edite o arquivo de configuração do próprio Claude Desktop para o seu sistema operacional (isso é a configuração do launcher do Claude Desktop, não squidex.config.json de Perfis abaixo — o bloco env aqui apenas define variáveis de ambiente para o processo que o 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"
      }
    }
  }
}

Reinicie o cliente após editar.

3. Experimente

Pergunte ao seu assistente algo como "Liste os esquemas de conteúdo no meu aplicativo Squidex". Se ele responder com seus esquemas, está funcionando.

Alternativa: binário independente (sem necessidade de Node.js)

Se Node.js/npx não estiver disponível, baixe um binário pré-compilado da página de Releases:

SO	Arquivo
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`

Torne-o executável no macOS/Linux (chmod +x ~/Downloads/squidex-mcp-<your-platform>; o macOS também pode exigir xattr -d com.apple.quarantine <file>, pois não é notarizado) e use seu caminho absoluto como command em vez de npx na configuração acima (e remova as partes args/-y, que são específicas do npx).

Perfis (múltiplas instâncias Squidex)

Se você precisar de mais de um aplicativo/instância Squidex (ex.: produção + homologação) acessível a partir do mesmo servidor, use um arquivo squidex.config.json em vez de variáveis de ambiente:

{
  "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": "..." }
  }
}

Toda ferramenta aceita um parâmetro opcional profile para escolher qual destino usar — sem necessidade de reiniciar o servidor para alternar. O arquivo é relido a cada chamada. requestTimeoutMs (padrão 15000) se aplica a cada requisição HTTP do Squidex em todos os perfis.

Por padrão, o servidor procura por squidex.config.json no diretório de trabalho atual; aponte para outro lugar com a variável de ambiente SQUIDEX_MCP_CONFIG (caminho absoluto recomendado, pois o diretório de trabalho do processo cliente nem sempre é previsível). Se nenhum arquivo de configuração for encontrado, as quatro variáveis de ambiente SQUIDEX_* do Início rápido são usadas como um único perfil default implícito.

Os dados de campo de conteúdo já devem estar formatados conforme o particionamento do Squidex ({ "title": { "iv": "..." } } para campos invariantes, { "en": "...", "de": "..." } para os localizados) — chame schema_get primeiro para ver o modo de cada campo e language_list para ver quais códigos de idioma estão realmente configurados no aplicativo.

Desenvolvimento

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

Aponte seu cliente MCP para bun run src/index.ts neste diretório em vez de um binário baixado durante o desenvolvimento.

bun run build produz o dist/index.js direcionado ao Node que é publicado no npm (as dependências permanecem externas — instaladas normalmente via npm/npx, não incluídas). Separadamente, bun run build:binary compila um binário independente apenas para o seu sistema operacional atual (dist/squidex-mcp); bun run build:binary:all cross-compila todos os cinco alvos de release de uma vez (dist/squidex-mcp-<platform>) — o mesmo comando que release.yml executa quando uma tag é enviada.

Squidex local para testes de ponta a ponta

docker-compose.yml executa um Squidex local + MongoDB para testes reais (não simulados):

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 é idempotente — seguro reexecutar contra uma instância já inicializada. Ele autentica como o cliente superadmin root (criado via IDENTITY__ADMINCLIENTID/IDENTITY__ADMINCLIENTSECRET em docker-compose.yml, credenciais apenas de desenvolvimento, não segredos reais) e escreve um perfil local em squidex.config.json.

docker compose down o interrompe; adicione -v para também apagar o volume do Mongo (Squidex limpo no próximo up).

Publicação

Enviar uma tag correspondente a v*.*.* aciona .github/workflows/release.yml: ele executa a suíte de testes, publica o pacote no npm, cross-compila binários independentes para Linux/macOS/Windows e os anexa a um GitHub Release.

git tag v0.2.0
git push origin v0.2.0

Publicar no npm usa Trusted Publishing (OIDC) — sem token/segredo necessário. Configuração única: publique a primeira versão manualmente (npm login && npm publish --access public, pois a configuração do Trusted Publisher exige que o pacote já exista) e, nas configurações do pacote em npmjs.com, adicione um Trusted Publisher apontando para este repositório (francyfox/squidex-mcp) e arquivo de workflow (release.yml). Depois disso, todo envio de tag publica automaticamente.