ElmapiCMS MCP Server

1# ElmapiCMS MCP Server
2 
3An 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.
4 
5## Installation
6 
7```bash
8npm install -g @elmapicms/mcp-server
9```
10 
11Or install locally:
12 
13```bash
14npm install @elmapicms/mcp-server
15```
16 
17## Configuration
18 
19The server requires three environment variables:
20 
21| Variable            | Description                                        |
22|---------------------|----------------------------------------------------|
23| `ELMAPI_API_URL`    | Base API URL (e.g., `https://your-domain.com/api`) |
24| `ELMAPI_API_KEY`    | API token with the required abilities               |
25| `ELMAPI_PROJECT_ID` | Project UUID                                        |
26 
27## Usage with Cursor
28 
29Add this to your Cursor MCP settings (`~/.cursor/mcp.json`):
30 
31```json
32{
33  "mcpServers": {
34    "elmapicms": {
35      "command": "npx",
36      "args": ["@elmapicms/mcp-server"],
37      "env": {
38        "ELMAPI_API_URL": "https://your-domain.com/api",
39        "ELMAPI_API_KEY": "your-api-key",
40        "ELMAPI_PROJECT_ID": "your-project-uuid"
41      }
42    }
43  }
44}
45```
46 
47## Usage with Claude Code
48 
49Add the MCP server using the Claude Code CLI:
50 
51```bash
52claude mcp add elmapicms \
53  -e ELMAPI_API_URL=https://your-domain.com/api \
54  -e ELMAPI_API_KEY=your-api-key \
55  -e ELMAPI_PROJECT_ID=your-project-uuid \
56  -- npx @elmapicms/mcp-server
57```
58 
59## Local Development (Laravel Herd / .test domains)
60 
61If 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:
62 
63```json
64"env": {
65  "ELMAPI_API_URL": "https://myproject.test/api",
66  "ELMAPI_API_KEY": "your-api-key",
67  "ELMAPI_PROJECT_ID": "your-project-uuid",
68  "NODE_TLS_REJECT_UNAUTHORIZED": "0"
69}
70```
71 
72> **Note:** Only use `NODE_TLS_REJECT_UNAUTHORIZED=0` for local development. Do not use this in production.
73 
74## Available Tools (17)
75 
76### Project
77- `get_project` — Get project information
78 
79### Collections
80- `list_collections` — List all collections
81- `get_collection` — Get a collection with its full field schema
82- `create_collection` — Create a collection (with optional batch field creation)
83- `update_collection` — Update a collection's name and slug
84- `reorder_collections` — Reorder collections
85 
86### Fields
87- `create_field` — Add a field to a collection
88- `update_field` — Update a field
89- `reorder_fields` — Reorder fields within a collection
90 
91### Content Entries
92- `list_entries` — List entries with advanced filtering (`where` with 13 operators, OR groups, relation filtering), sorting, pagination, count, and first
93- `get_entry` — Get a single content entry
94- `create_entry` — Create a content entry
95- `update_entry` — Update a content entry
96- `delete_entry` — Soft-delete a content entry (moves to trash)
97 
98### Assets
99- `list_assets` — List assets with pagination
100- `get_asset` — Get an asset by UUID or filename
101- `upload_asset` — Upload a file as an asset
102- `delete_asset` — Delete an asset
103 
104## Resources
105 
106The server exposes three reference resources that AI agents can read for context:
107 
108- **Field Types Reference** (`elmapicms://field-types`) — Complete reference of all 16 field types, their options, validations, and common patterns.
109- **Collections Guide** (`elmapicms://collections-guide`) — Guide for working with collections, singletons, reserved slugs, and best practices.
110- **Query Reference** (`elmapicms://query-reference`) — Full documentation for content queries: `where` filters with 13 operators, OR groups, relation filtering, sorting, pagination, and examples.
111 
112## Token Abilities
113 
114Your API token needs the appropriate abilities for the tools you want to use:
115 
116| Ability  | Tools                                                       |
117|----------|-------------------------------------------------------------|
118| `read`   | list/get collections, entries, assets                        |
119| `create` | create entries, upload assets                                |
120| `update` | update entries                                               |
121| `delete` | delete entries, delete assets                                |
122| `admin`  | create/update/reorder collections and fields                 |
123 
124You can generate API tokens from your project's **Settings > API Access** page.
125 
126## Using Multiple Projects
127 
128Each MCP server instance connects to a single project. To work with multiple projects, add separate entries in your MCP config:
129 
130```json
131{
132  "mcpServers": {
133    "elmapicms-blog": {
134      "command": "npx",
135      "args": ["@elmapicms/mcp-server"],
136      "env": {
137        "ELMAPI_API_URL": "https://your-domain.com/api",
138        "ELMAPI_API_KEY": "blog-project-api-key",
139        "ELMAPI_PROJECT_ID": "blog-project-uuid"
140      }
141    },
142    "elmapicms-store": {
143      "command": "npx",
144      "args": ["@elmapicms/mcp-server"],
145      "env": {
146        "ELMAPI_API_URL": "https://your-domain.com/api",
147        "ELMAPI_API_KEY": "store-project-api-key",
148        "ELMAPI_PROJECT_ID": "store-project-uuid"
149      }
150    }
151  }
152}
153```
154 
155## License
156 
157MIT
158