contentful-mcp
by: ivo-toby
MCP (Model Context Protocol) server for the Contentful Management API
📌Overview
Purpose: To provide a comprehensive MCP (Management Control Protocol) server that integrates with Contentful's Content Management API for efficient content management.
Overview: The Contentful MCP Server allows users to perform a variety of content management tasks, including managing entries, assets, spaces, and content types. It offers bulk operations, localization support, and an efficient pagination system to optimize the handling of large datasets.
Key Features:
-
Content Management: Supports full CRUD (Create, Read, Update, Delete) operations for entries and assets, enabling users to easily manage content.
-
Bulk Operations: Facilitates the simultaneous processing of multiple content items with features for asynchronous operation and status tracking, streamlining content migrations and updates.
-
Smart Pagination: Implements a controlled pagination system that limits the number of items returned per request to ensure efficient handling of larger data sets without overwhelming the system context.
Contentful MCP Server
An MCP server implementation that integrates with Contentful's Content Management API, providing comprehensive content management capabilities.
If you just want to use this MCP in Claude Desktop (or any other tool that supports MCP servers), you don't need to clone this repo. Refer to the section Usage with Claude Desktop for installation instructions.
Features
- Content Management: Full CRUD operations for entries and assets.
- Space Management: Create, update, and manage spaces and environments.
- Content Types: Manage content type definitions.
- Localization: Support for multiple locales.
- Publishing: Control content publishing workflow.
- Bulk Operations: Execute bulk publishing, unpublishing, and validation across multiple entries and assets.
- Smart Pagination: List operations return a maximum of 3 items per request to prevent context window overflow, with built-in pagination support.
Pagination
To prevent context window overflow in LLMs, list operations (like search_entries and list_assets) are limited to 3 items per request. Each response includes:
- Total number of available items.
- Current page of items (max 3).
- Number of remaining items.
- Skip value for the next page.
- Message prompting the LLM to offer retrieving more items.
This system enables efficient handling of large datasets while maintaining context window limits.
Bulk Operations
Bulk operations provide efficient management of multiple content items simultaneously:
- Asynchronous Processing with status updates.
- Efficient Content Management by processing multiple entries or assets in a single API call.
- Status Tracking, including success and failure counts.
- Resource Optimization to reduce API calls and improve performance.
Ideal for content migrations, mass updates, or batch publishing workflows.
Tools
Entry Management
search_entries
: Search for entries using query parameters.create_entry
: Create new entries.get_entry
: Retrieve existing entries.update_entry
: Update entry fields.delete_entry
: Remove entries.publish_entry
: Publish entries.unpublish_entry
: Unpublish entries.
Bulk Operations
bulk_publish
: Publish multiple entries and assets as a batch.bulk_unpublish
: Unpublish multiple entries and assets as a batch.bulk_validate
: Validate multiple entries for consistency and required fields.
Asset Management
list_assets
: List assets with pagination (3 items per page).upload_asset
: Upload new assets with metadata.get_asset
: Retrieve asset details.update_asset
: Update asset metadata and files.delete_asset
: Remove assets.publish_asset
: Publish assets.unpublish_asset
: Unpublish assets.
Space & Environment Management
list_spaces
: List available spaces.get_space
: Get space details.list_environments
: List environments.create_environment
: Create new environment.delete_environment
: Remove environment.
Content Type Management
list_content_types
: List content types.get_content_type
: Get content type details.create_content_type
: Create new content type.update_content_type
: Update content type.delete_content_type
: Remove content type.publish_content_type
: Publish a content type.
Development Tools
MCP Inspector
A tool for development and debugging:
- Run
npm run inspect
and open http://localhost:5173 for the inspector UI. - Use
npm run inspect:watch
to auto-restart on file changes. - Test and debug MCP tools in real-time with a web interface.
- Monitor bulk operations visually.
The project also supports npm run dev
to rebuild and reload the MCP server on every change.
Configuration
Prerequisites
- Create a Contentful account at https://www.contentful.com/
- Generate a Content Management API token.
Environment Variables
These can be set via environment variables or command line arguments:
CONTENTFUL_HOST
/--host
: Contentful Management API Endpoint (default: https://api.contentful.com).CONTENTFUL_MANAGEMENT_ACCESS_TOKEN
/--management-token
: Content Management API token.
Space and Environment Scoping (EXPERIMENTAL)
You can scope operations to a specific space and environment:
- Set
SPACE_ID
andENVIRONMENT_ID
environment variables or use--space-id
and--environment-id
arguments. - When set, tools for managing multiple spaces are unavailable.
Using App Identity
Instead of a management token, you can use Contentful App Identity for authentication:
- Parameters required:
--app-id
: App ID providing the token.--private-key
: Private key from the app.--space-id
: Space ID where the app is installed.--environment-id
: Environment ID within the space.
The MCP server will request a temporary token for defined space/environment, useful for backend systems or chat agents.
Usage with Claude Desktop
You do not need to clone this repo to use this MCP. Simply add it to your claude_desktop_config.json
located at:
~/Library/Application Support/Claude/claude_desktop_config.json
Example configuration:
{
"mcpServers": {
"contentful": {
"command": "npx",
"args": ["-y", "@ivotoby/contentful-management-mcp-server"],
"env": {
"CONTENTFUL_MANAGEMENT_ACCESS_TOKEN": "<Your CMA token>"
}
}
}
}
If your client cannot set environment variables, you can specify the token via arguments:
{
"mcpServers": {
"contentful": {
"command": "npx",
"args": ["-y", "@ivotoby/contentful-management-mcp-server", "--management-token", "<your token>", "--host", "https://api.contentful.com"]
}
}
}
Installing via Smithery
To install the Contentful Management Server automatically for Claude Desktop via Smithery:
npx -y @smithery/cli install @ivotoby/contentful-management-mcp-server --client claude
Developing and Using Claude Desktop
To contribute and test:
- Run
npm run dev
to watch and rebuild the server automatically. - Update
claude_desktop_config.json
to reference the local project:
{
"mcpServers": {
"contentful": {
"command": "node",
"args": ["/path/to/contentful-mcp/bin/mcp-server.js"],
"env": {
"CONTENTFUL_MANAGEMENT_ACCESS_TOKEN": "<Your CMA Token>"
}
}
}
}
Restart Claude Desktop after adding new tools/resources.
Error Handling
The server handles errors related to:
- Authentication failures.
- Rate limiting.
- Invalid requests.
- Network issues.
- API-specific errors.
License
MIT License
Disclaimer
This MCP Server allows agents like Claude to update and delete content, spaces, and content models in your Contentful account. Use with caution and ensure you trust the agent's permissions on your Contentful spaces.