NomaCMS MCP Server

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

Configuration

• `NOMA_API_KEY`: API key from User settings → API keys — see API key abilities.
• `NOMA_PROJECT_ID`: Your project's UUID — you can find it on the project home page or under Project settings → API Access

Usage with Cursor

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

{
  "mcpServers": {
    "nomacms": {
      "command": "npx",
      "args": ["-y", "@nomacms/mcp-server"],
      "env": {
        "NOMA_API_KEY": "your-api-key",
        "NOMA_PROJECT_ID": "your-project-uuid"
      }
    }
  }
}

Usage with Claude Code

Add the MCP server using the Claude Code CLI:

claude mcp add nomacms \
  -e NOMA_API_KEY=your-api-key \
  -e NOMA_PROJECT_ID=your-project-uuid \
  -- npx -y @nomacms/mcp-server

Available Tools (39)

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 NomaCMS dashboard if you must remove a locale).

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)
• `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 ability)
• `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). Richtext values are markdown strings on write; on read they are either raw markdown or rendered HTML depending on the field’s `editor.outputFormat` (`markdown` vs `html`). 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.

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

API key abilities

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

Create the key in the NomaCMS dashboard under User settings → API keys. 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 NomaCMS project. To work with multiple projects, add separate entries in your MCP config:

{
  "mcpServers": {
    "nomacms-blog": {
      "command": "npx",
      "args": ["-y", "@nomacms/mcp-server"],
      "env": {
        "NOMA_API_KEY": "blog-project-api-key",
        "NOMA_PROJECT_ID": "blog-project-uuid"
      }
    },
    "nomacms-store": {
      "command": "npx",
      "args": ["-y", "@nomacms/mcp-server"],
      "env": {
        "NOMA_API_KEY": "store-project-api-key",
        "NOMA_PROJECT_ID": "store-project-uuid"
      }
    }
  }
}

License

MIT