ElmapiCMS MCP Server

An MCP (Model Context Protocol) server that connects AI agents like Cursor and Claude Code to your ElmapiCMS instance. Manage collections, fields, content entries, assets, and webhooks programmatically through natural language.

Configuration

Usage with Cursor

Add this to your Cursor MCP settings (`~/.cursor/mcp.json`):

{
  "mcpServers": {
    "elmapicms": {
      "command": "npx",
      "args": ["-y", "@elmapicms/mcp-server"],
      "env": {
        "ELMAPI_BASE_URL": "https://your-domain.com/api",
        "ELMAPI_API_KEY": "your-project-api-token",
        "ELMAPI_PROJECT_ID": "your-project-uuid"
      }
    }
  }
}

Usage with Claude Code

claude mcp add elmapicms \
  -e ELMAPI_BASE_URL=https://your-domain.com/api \
  -e ELMAPI_API_KEY=your-project-api-token \
  -e ELMAPI_PROJECT_ID=your-project-uuid \
  -- npx -y @elmapicms/mcp-server

Local Development (Laravel Herd / `.test` domains)

If your instance uses a self-signed certificate (e.g. Laravel Herd), you may need:

"env": {
  "ELMAPI_BASE_URL": "https://myproject.test/api",
  "ELMAPI_API_KEY": "your-project-api-token",
  "ELMAPI_PROJECT_ID": "your-project-uuid",
  "NODE_TLS_REJECT_UNAUTHORIZED": "0"
}

Prefer fixing local CA trust (e.g. `node --use-system-ca`) over disabling TLS verification in production configs.

Available Tools (40)

Project

• `get_project` — Get project information (`default_locale`, `locales`, etc.)
• `add_project_locale` — Add a locale code to the project (requires admin)
• `set_default_project_locale` — Set the default locale (requires admin)

Removing locales is intentionally not exposed here (use Project settings → Localization in the dashboard, or the REST/SDK APIs).

Collections

• `list_collections` — List all collections
• `get_collection` — Get a collection with its full field schema
• `create_collection` — Create a collection (with optional batch field creation)
• `update_collection` — Update a collection's name and slug
• `reorder_collections` — Reorder collections

Fields

• `create_field` — Add a field to a collection
• `update_field` — Update a field
• `reorder_fields` — Reorder fields within a collection

Content Entries

• `list_entries` — List entries with advanced filtering (`where` with 13 operators, OR groups, relation filtering), sorting, pagination, count, and first
• `get_entry` — Get a single content entry
• `create_entry` — Create a content entry
• `update_entry` — Update a content entry
• `patch_entry` — Partially update an entry (HTTP PATCH; merge only the fields you send)
• `publish_entry` — Publish the draft as a new immutable version (update)
• `unpublish_entry` — Clear the live published pointer; versions retained (update)
• `discard_entry_draft` — Discard unpublished draft changes (update)
• `delete_entry` — Soft-delete a content entry (moves to trash)
• `bulk_create_entries` — Create multiple entries atomically
• `bulk_update_entries` — Update multiple entries atomically by UUID
• `bulk_delete_entries` — Delete multiple entries atomically by UUID
• `link_entry_translation` — Link two entries (different locales) into the same translation group (`POST …/link-translation`; requires update)
• `list_entry_versions` — List version history for an entry
• `get_entry_version` — Fetch one version by number (includes snapshot payload)
• `revert_entry_version` — Restore draft from a prior snapshot and publish (update)
• `update_entry_version_label` — Edit label/description on a version; snapshot unchanged (update)

Content API shape: Each entry has `uuid`, `locale`, `published_at`, and `fields` (custom field values). Field names are kebab-case. Richtext write format follows `editor.mode`: HTML string or `{ html, json }` for lexical; markdown string when `mode` is `markdown`. MCP create_field / create_collection (and richtext update_field) default omitted `editor.mode` to markdown. Pass `mode: 'lexical'` for Lexical. Never write markdown into a lexical field. Read shape follows `editor.outputFormat`. Relation fields return nested entry objects (or arrays for one-to-many) on read; on write send only the related entry’s UUID or numeric id (never the full nested object from a previous `get_entry`). `get_entry` supports `translation_locale`, `exclude`, `timestamps`, and `state` query parameters.

Save ≠ publish: `create_entry` / `update_entry` / `patch_entry` save the draft only. `state=published` list/get keep serving the last snapshot until you call `publish_entry`.

Asset URLs: The API returns `url`, `thumbnail_url`, and `original_url` as stable links (optional `?variant=thumbnail` or `?variant=original`).

Assets

• `list_assets` — List assets with pagination
• `get_asset` — Get an asset by UUID or filename
• `upload_asset` — Upload a file as an asset
• `bulk_upload_assets` — Upload multiple files atomically
• `bulk_update_asset_metadata` — Update metadata for multiple assets atomically
• `delete_asset` — Delete an asset

Webhooks

• `list_webhooks` — List all webhooks for the project
• `get_webhook` — Get a webhook by UUID
• `create_webhook` — Create a webhook for content and auth events (`name`, `url`, `events`, `sources`; optional `description`, `secret`, `payload`, `status`, `collection_ids`)
• `update_webhook` — Update a webhook by UUID (same fields as create)
• `delete_webhook` — Delete a webhook by UUID
• `list_webhook_logs` — List delivery logs for a webhook (`uuid`; optional `paginate`, `page`)

Resources

The server exposes three reference resources that AI agents can read for context:

• Field Types Reference (`elmapicms://field-types`) — Complete reference of all 16 field types, their options, validations, and common patterns.
• Collections Guide (`elmapicms://collections-guide`) — Guide for working with collections, singletons, reserved slugs, and best practices.
• Query Reference (`elmapicms://query-reference`) — Full documentation for content queries: `where` filters with 13 operators, OR groups, relation filtering, sorting, pagination, and examples.

API token abilities

Your project API token needs the appropriate abilities for the tools you want to use:

Create the token in the ElmapiCMS dashboard under Project settings → API Tokens. Copy the Project ID from the project home page or Project settings → API Access when you configure this server.

Using Multiple Projects

Each MCP entry connects to a single ElmapiCMS project. To work with multiple projects, add separate entries in your MCP config with different env values.

License

MIT