NomaCMS MCP Server
MCP server for NomaCMS. Manage collections, fields, content, assets, and webhooks via AI agents.
Open source Open in the app JSON README (API)
About
MCP server for NomaCMS. Manage collections, fields, content, assets, and webhooks via AI agents.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- nomacms
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.2.2
- Stars
- 1
- Last push
- 2026-07-15T18:24:48Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:08
- Updated
- 2026-08-29 03:02:08
- Origin id
io.github.NomaCMS/nomacms-mcp-server
README
# NomaCMS MCP Server
An MCP (Model Context Protocol) server that connects AI agents like [Cursor](https://cursor.com) and [Claude Code](https://claude.com/product/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](#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`):
```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:
```bash
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:
| Ability | Tools |
|----------|-------------------------------------------------------------|
| `read` | list/get collections, entries, assets, webhooks; webhook logs |
| `create` | create entries, upload assets, create webhooks |
| `update` | update entries, **`link_entry_translation`**, 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 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:
```json
{
"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