squidex-mcp (non-official)

An MCP (Model Context Protocol) server that lets AI agents read and write Squidex CMS content directly. MCP is an open, model-agnostic protocol — any compliant client works (Claude Code, Claude Desktop, Cursor, Windsurf, custom agents on any model), not just Anthropic's. Built on Bun for fast, dependency-free startup — each agent session spawns its own server process over stdio.

What it can do

It can target multiple Squidex apps/instances (e.g. prod + staging) from one running server — every tool takes an optional `profile` parameter, switchable without restarting the server. See Profiles below.

Quick start (no coding required)

The easiest way to run it is via `npx` — no download, no build step, just a Node.js install (which most machines already have).

1. Get your Squidex credentials

In your Squidex app: Settings → Clients → create (or copy) a client. You need:

• your Squidex URL (e.g. `https://cloud.squidex.io`)
• your app name
• the client ID (looks like `your-app-name:default`)
• the client secret

2. Register the server with your MCP client

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` makes it available in every project, not just the current one. `-y` stops `npx` from pausing on an interactive "ok to install?" prompt, which would otherwise hang the connection on first run.

Claude Desktop: edit *Claude Desktop's own* config file for your OS (this is Claude Desktop's launcher config, not `squidex.config.json` from Profiles below — the `env` block here just sets environment variables for the process Claude Desktop spawns) —

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"
      }
    }
  }
}

Restart the client after editing.

3. Try it

Ask your assistant something like *"List the content schemas in my Squidex app"*. If it replies with your schemas, it's working.

Alternative: standalone binary (no Node.js needed)

If Node.js/npx isn't available, download a prebuilt binary from the Releases page instead:

Make it executable on macOS/Linux (`chmod +x ~/Downloads/squidex-mcp-`; macOS may also require `xattr -d com.apple.quarantine ` since it isn't notarized), then use its absolute path as `command` instead of `npx` in the config above (and drop the `args`/`-y` bits, which are npx-specific).

Profiles (multiple Squidex instances)

If you need more than one Squidex app/instance (e.g. prod + staging) reachable from the same server, use a `squidex.config.json` file instead of env vars:

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

Every tool accepts an optional `profile` parameter to pick which target to use — no server restart needed to switch. The file is re-read on every call. `requestTimeoutMs` (default 15000) applies to every Squidex HTTP request across all profiles.

By default the server looks for `squidex.config.json` in its current working directory; point it elsewhere with the `SQUIDEX_MCP_CONFIG` env var (absolute path recommended, since the client process's working directory isn't always predictable). If no config file is found at all, the four `SQUIDEX_*` env vars from Quick start are used as a single implicit `default` profile.

Content field data must already be shaped per Squidex's partitioning (`{ "title": { "iv": "..." } }` for invariant fields, `{ "en": "...", "de": "..." }` for localized ones) — call `schema_get` first to see each field's mode, and `language_list` to see which language codes are actually configured on the app.

Development

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

Point your MCP client at `bun run src/index.ts` in this directory instead of a downloaded binary while developing.

`bun run build` produces the Node-targeted `dist/index.js` that gets published to npm (dependencies stay external — installed normally via npm/npx, not bundled). Separately, `bun run build:binary` compiles a standalone binary for your current OS only (`dist/squidex-mcp`); `bun run build:binary:all` cross-compiles all five release targets at once (`dist/squidex-mcp-`) — the same command `release.yml` runs when a tag is pushed.

Local Squidex for end-to-end testing

`docker-compose.yml` runs a local Squidex + MongoDB for real (non-mocked) testing:

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` is idempotent — safe to re-run against an already-bootstrapped instance. It authenticates as the `root` superadmin client (created via `IDENTITY__ADMINCLIENTID`/`IDENTITY__ADMINCLIENTSECRET` in `docker-compose.yml`, dev-only credentials, not real secrets) and writes a `local` profile into `squidex.config.json`.

`docker compose down` stops it; add `-v` to also wipe the Mongo volume (fresh Squidex on next `up`).

Releasing

Pushing a tag matching `v*.*.*` triggers `.github/workflows/release.yml`: it runs the test suite, publishes the package to npm, cross-compiles standalone binaries for Linux/macOS/Windows, and attaches them to a GitHub Release.

git tag v0.2.0
git push origin v0.2.0

Publishing to npm uses Trusted Publishing (OIDC) — no token/secret needed. One-time setup: publish the first version manually (`npm login && npm publish --access public`, since Trusted Publisher configuration requires the package to already exist), then on the package's npmjs.com settings add a Trusted Publisher pointing at this repo (`francyfox/squidex-mcp`) and workflow file (`release.yml`). After that, every tag push publishes automatically.