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

| Variable | Description | |----------|-------------| | ELMAPI_BASE_URL | Instance API root (e.g. https://your-domain.com/api). ELMAPI_API_URL is accepted as an alias. | | ELMAPI_API_KEY | Project Sanctum token from Project settings → API Tokens | | ELMAPI_PROJECT_ID | Project UUID from the project home page or Project settings → API Access |

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:

| Ability | Tools | |----------|-------------------------------------------------------------| | read | list/get collections, entries, assets, webhooks; webhook logs | | create | create entries, upload assets, create webhooks | | update | update entries, publish/unpublish/discard draft, link_entry_translation, versions, update asset metadata, update webhooks | | delete | delete entries, delete assets, delete webhooks | | admin | create/update/reorder collections and fields; add/set default project locales (MCP does not expose locale removal) |

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