Contentful MCP Server

1<img width="700" src="https://images.ctfassets.net/jtqsy5pye0zd/6wNuQ2xMvbw134rccObi0q/bf61badc6d6d9780609e541713f0bba6/Contentful_Logo_2.5_Dark.svg?w=700&q=100" alt="Contentful MCP server"/>
2 
3# Contentful MCP Server
4 
5## Notice
6 
7This is a community driven server! Contentful has released an official server which you can find [here](https://github.com/contentful/contentful-mcp-server)
8 
9[![smithery badge](https://smithery.ai/badge/@ivotoby/contentful-management-mcp-server)](https://smithery.ai/server/@ivotoby/contentful-management-mcp-server)
10 
11An MCP server implementation that integrates with Contentful's Content Management API, providing comprehensive content management capabilities.
12 
13- Please note \*; if you are not interested in the code, and just want to use this MCP in
14  Claude Desktop (or any other tool that is able to use MCP servers) you don't have to
15  clone this repo, you can just set it up in Claude desktop, refer to the section
16  "Usage with Claude Desktop" for instructions on how to install it.
17 
18<a href="https://glama.ai/mcp/servers/l2fxeaot4p"><img width="380" height="200" src="https://glama.ai/mcp/servers/l2fxeaot4p/badge" alt="contentful-mcp MCP server" /></a>
19 
20## Features
21 
22- **Content Management**: Full CRUD operations for entries and assets
23- **Comment Management**: Create, retrieve, and manage comments on entries with support for both plain-text and rich-text formats, including threaded conversations
24- **Space Management**: Create, update, and manage spaces and environments
25- **Content Types**: Manage content type definitions
26- **Localization**: Support for multiple locales
27- **Publishing**: Control content publishing workflow
28- **Bulk Operations**: Execute bulk publishing, unpublishing, and validation across multiple entries and assets
29- **Smart Pagination**: List operations return maximum 3 items per request to prevent context window overflow, with built-in pagination support
30 
31## Pagination
32 
33To prevent context window overflow in LLMs, list operations (like search_entries and list_assets) are limited to 3 items per request. Each response includes:
34 
35- Total number of available items
36- Current page of items (max 3)
37- Number of remaining items
38- Skip value for the next page
39- Message prompting the LLM to offer retrieving more items
40 
41This pagination system allows the LLM to efficiently handle large datasets while maintaining context window limits.
42 
43## Bulk Operations
44 
45The bulk operations feature provides efficient management of multiple content items simultaneously:
46 
47- **Asynchronous Processing**: Operations run asynchronously and provide status updates
48- **Efficient Content Management**: Process multiple entries or assets in a single API call
49- **Status Tracking**: Monitor progress with success and failure counts
50- **Resource Optimization**: Reduce API calls and improve performance for batch operations
51 
52These bulk operation tools are ideal for content migrations, mass updates, or batch publishing workflows.
53 
54## Tools
55 
56### Entry Management
57 
58- **search_entries**: Search for entries using query parameters
59- **create_entry**: Create new entries
60- **get_entry**: Retrieve existing entries
61- **update_entry**: Update entry fields
62- **delete_entry**: Remove entries
63- **publish_entry**: Publish entries
64- **unpublish_entry**: Unpublish entries
65 
66### Comment Management
67 
68- **get_comments**: Retrieve comments for an entry with filtering by status (active, resolved, all)
69- **create_comment**: Create new comments on entries with support for both plain-text and rich-text formats. Supports threaded conversations by providing a parent comment ID to reply to existing comments
70- **get_single_comment**: Retrieve a specific comment by its ID for an entry
71- **delete_comment**: Delete a specific comment from an entry
72- **update_comment**: Update existing comments with new body content or status changes
73 
74#### Threaded Comments
75 
76Comments support threading functionality to enable structured conversations and work around the 512-character limit:
77 
78- **Reply to Comments**: Use the `parent` parameter in `create_comment` to reply to an existing comment
79- **Threaded Conversations**: Build conversation trees by replying to specific comments
80- **Extended Discussions**: Work around the 512-character limit by creating threaded replies to continue longer messages
81- **Conversation Context**: Maintain context in discussions by organizing related comments in threads
82 
83Example usage:
84 
851. Create a main comment: `create_comment` with `entryId`, `body`, and `status`
862. Reply to that comment: `create_comment` with `entryId`, `body`, `status`, and `parent` (the ID of the comment you're replying to)
873. Continue the thread: Reply to any comment in the thread by using its ID as the `parent`
88 
89### Bulk Operations
90 
91- **bulk_publish**: Publish multiple entries and assets in a single operation. Accepts an array of entities (entries and assets) and processes their publication as a batch.
92- **bulk_unpublish**: Unpublish multiple entries and assets in a single operation. Similar to bulk_publish but removes content from the delivery API.
93- **bulk_validate**: Validate multiple entries for content consistency, references, and required fields. Returns validation results without modifying content.
94 
95### Asset Management
96 
97- **list_assets**: List assets with pagination (3 items per page)
98- **upload_asset**: Upload new assets with metadata
99- **get_asset**: Retrieve asset details and information
100- **update_asset**: Update asset metadata and files
101- **delete_asset**: Remove assets from space
102- **publish_asset**: Publish assets to delivery API
103- **unpublish_asset**: Unpublish assets from delivery API
104 
105### Space & Environment Management
106 
107- **list_spaces**: List available spaces
108- **get_space**: Get space details
109- **list_environments**: List environments in a space
110- **create_environment**: Create new environment
111- **delete_environment**: Remove environment
112 
113### Content Type Management
114 
115- **list_content_types**: List available content types
116- **get_content_type**: Get content type details
117- **create_content_type**: Create new content type
118- **update_content_type**: Update content type
119- **delete_content_type**: Remove content type
120- **publish_content_type**: Publish a content type
121 
122## Development Tools
123 
124### MCP Inspector
125 
126The project includes an MCP Inspector tool that helps with development and debugging:
127 
128- **Inspect Mode**: Run `npm run inspect` to start the inspector, you can open the inspector by going to http://localhost:5173
129- **Watch Mode**: Use `npm run inspect:watch` to automatically restart the inspector when files change
130- **Visual Interface**: The inspector provides a web interface to test and debug MCP tools
131- **Real-time Testing**: Try out tools and see their responses immediately
132- **Bulk Operations Testing**: Test and monitor bulk operations with visual feedback on progress and results
133 
134The project also contains a `npm run dev` command which rebuilds and reloads the MCP server on every change.
135 
136## Configuration
137 
138### Prerequisites
139 
1401. Create a Contentful account at [Contentful](https://www.contentful.com/)
1412. Generate a Content Management API token from your account settings
142 
143### Environment Variables
144 
145These variables can also be set as arguments
146 
147- `CONTENTFUL_HOST` / `--host`: Contentful Management API Endpoint (defaults to https://api.contentful.com)
148- `CONTENTFUL_MANAGEMENT_ACCESS_TOKEN` / `--management-token`: Your Content Management API token
149- `ENABLE_HTTP_SERVER` / `--http`: Set to "true" to enable HTTP/SSE mode
150- `HTTP_PORT` / `--port`: Port for HTTP server (default: 3000)
151- `HTTP_HOST` / `--http-host`: Host for HTTP server (default: localhost)
152- `DISABLE_AI_ACTIONS`: Set to "true" to disable fetching AI Actions on startup (useful if you don't have access to this feature)
153 
154### Space and Environment Scoping
155 
156You can scope the spaceId and EnvironmentId to ensure the LLM will only do operations on the defined space/env ID's.
157This is mainly to support agents that are to operate within specific spaces. If both `SPACE_ID` and `ENVIRONMENT_ID` env-vars are set
158the tools will not report needing these values and the handlers will use the environment vars to do CMA operations.
159You will also loose access to the tools in the space-handler, since these tools are across spaces.
160You can also add the `SPACE_ID` and `ENVIRONMENT_ID` by using arguments `--space-id` and `--environment-id`
161 
162#### Using App Identity
163 
164Instead of providing a Management token you can also leverage [App Identity](https://www.contentful.com/developers/docs/extensibility/app-framework/app-identity/)
165for handling authentication. You would have to setup and install a Contentful App and set the following parameters when calling the MCP-server:
166 
167- `--app-id` = the app Id which is providing the Apptoken
168- `--private-key` = the private key you created in the user-interface with your app, tied to `app_id`
169- `--space-id` = the spaceId in which the app is installed
170- `--environment-id` = the environmentId (within the space) in which the app is installed.
171 
172With these values the MCP server will request a temporary AppToken to do content operation in the defined space/environment-id. This especially useful when using this MCP server in backend systems that act as MCP-client (like chat-agents)
173 
174### Usage with Claude Desktop
175 
176You do not need to clone this repo to use this MCP, you can simply add it to
177your `claude_desktop_config.json`:
178 
179Add or edit `~/Library/Application Support/Claude/claude_desktop_config.json`
180and add the following lines:
181 
182```json
183{
184  "mcpServers": {
185    "contentful": {
186      "command": "npx",
187      "args": ["-y", "@ivotoby/contentful-management-mcp-server"],
188      "env": {
189        "CONTENTFUL_MANAGEMENT_ACCESS_TOKEN": "<Your CMA token>"
190      }
191    }
192  }
193}
194```
195 
196If your MCPClient does not support setting environment variables you can also set the management token using an argument like this:
197 
198```json
199{
200  "mcpServers": {
201    "contentful": {
202      "command": "npx",
203      "args": [
204        "-y",
205        "@ivotoby/contentful-management-mcp-server",
206        "--management-token",
207        "<your token>",
208        "--host",
209        "http://api.contentful.com"
210      ]
211    }
212  }
213}
214```
215 
216### Installing via Smithery
217 
218To install Contentful Management Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@ivotoby/contentful-management-mcp-server):
219 
220```bash
221npx -y @smithery/cli install @ivotoby/contentful-management-mcp-server --client claude
222```
223 
224### Developing and using Claude desktop
225 
226If you want to contribute and test what Claude does with your contributions;
227 
228- run `npm run dev`, this will start the watcher that rebuilds the MCP server on every change
229- update `claude_desktop_config.json` to reference the project directly, ie;
230 
231```
232{
233  "mcpServers": {
234    "contentful": {
235      "command": "node",
236      "args": ["/Users/ivo/workspace/contentful-mcp/bin/mcp-server.js"],
237      "env": {
238        "CONTENTFUL_MANAGEMENT_ACCESS_TOKEN": "<Your CMA Token>"
239      }
240    }
241  }
242}
243```
244 
245This will allow you to test any modification in the MCP server with Claude directly, however; if you add new tools/resources you will need to restart Claude Desktop
246 
247## Transport Modes
248 
249The MCP server supports two transport modes:
250 
251### stdio Transport
252 
253The default transport mode uses standard input/output streams for communication. This is ideal for integration with MCP clients that support stdio transport, like Claude Desktop.
254 
255To use stdio mode, simply run the server without the `--http` flag:
256 
257```bash
258npx -y contentful-mcp --management-token YOUR_TOKEN
259# or alternatively
260npx -y @ivotoby/contentful-management-mcp-server --management-token YOUR_TOKEN
261```
262 
263### StreamableHTTP Transport
264 
265The server also supports the StreamableHTTP transport as defined in the MCP protocol. This mode is useful for web-based integrations or when running the server as a standalone service.
266 
267To use StreamableHTTP mode, run with the `--http` flag:
268 
269```bash
270npx -y contentful-mcp --management-token YOUR_TOKEN --http --port 3000
271# or alternatively
272npx -y @ivotoby/contentful-management-mcp-server --management-token YOUR_TOKEN --http --port 3000
273```
274 
275#### StreamableHTTP Details
276 
277- Uses the official MCP StreamableHTTP transport
278- Supports standard MCP protocol operations
279- Includes session management for maintaining state
280- Properly handles initialize/notify patterns
281- Compatible with standard MCP clients
282- Replaces the deprecated SSE transport with the modern approach
283 
284The implementation follows the standard MCP protocol specification, allowing any MCP client to connect to the server without special handling.
285 
286## Error Handling
287 
288The server implements comprehensive error handling for:
289 
290- Authentication failures
291- Rate limiting
292- Invalid requests
293- Network issues
294- API-specific errors
295 
296[![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/146d4235-bdb1-492e-b594-82fd27b77388)
297 
298## License
299 
300MIT License
301 
302## Fine print
303 
304This MCP Server enables Claude (or other agents that can consume MCP resources) to update, delete content, spaces and content-models. So be sure what you allow Claude to do with your Contentful spaces!
305 
306This MCP-server is not officially supported by Contentful (yet)
307