# ElmapiCMS 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 [ElmapiCMS](https://elmapicms.com) instance. Manage collections, fields, content entries, and assets programmatically through natural language.
## Installation
```bash
npm install -g @elmapicms/mcp-server
```
Or install locally:
```bash
npm install @elmapicms/mcp-server
```
## Configuration
The server requires three environment variables:
| Variable | Description |
|---------------------|----------------------------------------------------|
| `ELMAPI_API_URL` | Base API URL (e.g., `https://your-domain.com/api`) |
| `ELMAPI_API_KEY` | API token with the required abilities |
| `ELMAPI_PROJECT_ID` | Project UUID |
## Usage with Cursor
Add this to your Cursor MCP settings (`~/.cursor/mcp.json`):
```json
{
"mcpServers": {
"elmapicms": {
"command": "npx",
"args": ["@elmapicms/mcp-server"],
"env": {
"ELMAPI_API_URL": "https://your-domain.com/api",
"ELMAPI_API_KEY": "your-api-key",
"ELMAPI_PROJECT_ID": "your-project-uuid"
}
}
}
}
```
## Usage with Claude Code
Add the MCP server using the Claude Code CLI:
```bash
claude mcp add elmapicms \
-e ELMAPI_API_URL=https://your-domain.com/api \
-e ELMAPI_API_KEY=your-api-key \
-e ELMAPI_PROJECT_ID=your-project-uuid \
-- npx @elmapicms/mcp-server
```
## Local Development (Laravel Herd / .test domains)
If your ElmapiCMS instance runs on a `.test` domain with a self-signed SSL certificate (e.g., via Laravel Herd), add this to your env config:
```json
"env": {
"ELMAPI_API_URL": "https://myproject.test/api",
"ELMAPI_API_KEY": "your-api-key",
"ELMAPI_PROJECT_ID": "your-project-uuid",
"NODE_TLS_REJECT_UNAUTHORIZED": "0"
}
```
> **Note:** Only use `NODE_TLS_REJECT_UNAUTHORIZED=0` for local development. Do not use this in production.
## Available Tools (17)
### Project
- `get_project` — Get project information
### 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
- `delete_entry` — Soft-delete a content entry (moves to trash)
### Assets
- `list_assets` — List assets with pagination
- `get_asset` — Get an asset by UUID or filename
- `upload_asset` — Upload a file as an asset
- `delete_asset` — Delete an asset
## 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.
## Token Abilities
Your API token needs the appropriate abilities for the tools you want to use:
| Ability | Tools |
|----------|-------------------------------------------------------------|
| `read` | list/get collections, entries, assets |
| `create` | create entries, upload assets |
| `update` | update entries |
| `delete` | delete entries, delete assets |
| `admin` | create/update/reorder collections and fields |
You can generate API tokens from your project's **Settings > API Access** page.
## Using Multiple Projects
Each MCP server instance connects to a single project. To work with multiple projects, add separate entries in your MCP config:
```json
{
"mcpServers": {
"elmapicms-blog": {
"command": "npx",
"args": ["@elmapicms/mcp-server"],
"env": {
"ELMAPI_API_URL": "https://your-domain.com/api",
"ELMAPI_API_KEY": "blog-project-api-key",
"ELMAPI_PROJECT_ID": "blog-project-uuid"
}
},
"elmapicms-store": {
"command": "npx",
"args": ["@elmapicms/mcp-server"],
"env": {
"ELMAPI_API_URL": "https://your-domain.com/api",
"ELMAPI_API_KEY": "store-project-api-key",
"ELMAPI_PROJECT_ID": "store-project-uuid"
}
}
}
}
```
## License
MIT
