Contentful Management Server Implementation

This package furnishes an MCP service layer interfacing directly with the Contentful Content Management API, empowering extensive control over all managed resources.

Note for Consumers: If your primary goal is simply integration with client applications like Claude Desktop, local cloning of this repository is unnecessary. Refer to the "Client Integration Setup" section for direct installation instructions.

Core Capabilities

Data Entity Control: Complete lifecycle management (Create, Read, Update, Delete) for published items and associated media files.
Workspace Configuration: Tools for provisioning, modifying, and overseeing spaces and their isolated operational environments.
Schema Definition: Functionality to define and adjust content structure blueprints (Content Types).
Multilingual Support: Comprehensive handling for localized content variants.
Deployment Orchestration: Fine-grained control over the content publishing pipeline.
Batch Processing: High-throughput execution of publication, retraction, and integrity checks across large content sets.
Context-Aware Paging: List endpoints are constrained to return a maximum of 3 entities per invocation, mitigating context window exhaustion in requesting LLMs.

Context-Preserving Pagination Strategy

To maintain operational efficiency within constrained token limits (LLM context windows), all enumeration requests (e.g., asset listings, entry searches) cap results at three records. Each response packet contains:

Total record count available.
The subset of items retrieved for the current page (maximum 3).
The count of remaining entities not yet retrieved.
The necessary offset parameter for fetching the subsequent segment.
A directive encouraging the LLM to request further data if necessary.

This design ensures scalable data traversal without inducing context bloat.

Batch Processing Utilities

Batch functionalities enable efficient execution of concurrent operations on numerous content elements:

Asynchronous Execution: Operations are processed non-sequentially, providing periodic status feedback.
Consolidated Management: Streamlines the modification or deployment of multiple items via minimal API interactions.
Progress Monitoring: Detailed tracking of successful vs. failed operations.
Performance Gains: Substantially reduces network overhead compared to sequential single-item calls.

These utilities are optimized for large-scale content migration initiatives, mass updates, or high-volume deployment workflows.

Available Toolset

Content Entry Operations

search_entries: Query content entries based on specified criteria.
create_entry: Initialize a new content entry.
get_entry: Fetch details for an existing entry.
update_entry: Modify the fields of an entry.
delete_entry: Permanently remove an entry.
publish_entry: Promote an entry to the live Delivery API endpoint.
unpublish_entry: Retract an entry from the live Delivery API endpoint.

Bulk Actions

bulk_publish: Initiates batch publication for a collection of entries and assets.
bulk_unpublish: Initiates batch retraction for a collection of entries and assets.
bulk_validate: Performs integrity checks on a set of entities to verify field completeness and reference integrity, without altering state.

Media Asset Operations

list_assets: Retrieve a paginated list of assets (3 per page).
upload_asset: Ingest a new media asset along with its descriptive metadata.
get_asset: Retrieve specific asset metadata.
update_asset: Modify asset metadata or replace the underlying file content.
delete_asset: Erase an asset from the space.
publish_asset: Deploy an asset to the Delivery API.
unpublish_asset: Remove an asset from the Delivery API.

Workspace & Environment Control

list_spaces: Enumerate accessible Contentful spaces.
get_space: Retrieve metadata for a specific space.
list_environments: List all isolated environments within a space.
create_environment: Provision a new development/staging environment.
delete_environment: Decommission an existing environment.

Content Model Management

list_content_types: View defined content structures.
get_content_type: Inspect the definition of a specific content type.
create_content_type: Define a new content model.
update_content_type: Modify an existing content model's structure.
delete_content_type: Remove a content model.
publish_content_type: Deploy schema changes to make them live for use.

Development & Debugging Utilities

MCP Inspector Interface

The integrated Inspector aids in development and troubleshooting:

Launch Inspect Mode: Execute npm run inspect to start the local testing server. Access the UI via http://localhost:5173.
Watch/Reload: npm run inspect:watch ensures the inspector automatically restarts upon source code modification.
Graphical Testing: Provides a browser interface for interactive testing of all exposed tools.
Immediate Feedback: Observe tool outputs in real-time.
Batch Monitoring: Visual tracking of bulk operation progress and final outcomes.

The npm run dev script manages continuous server rebuilding and reloading upon file modifications.

Configuration Requirements

Prerequisites

Secure an active Contentful account via Contentful.
Generate a valid Content Management API Access Token from your user settings.

Environment Variables & Arguments

These parameters can be supplied via environment variables or command-line flags:

CONTENTFUL_HOST / --host: The base URL for the Contentful Management API (Default: https://api.contentful.com).
CONTENTFUL_MANAGEMENT_ACCESS_TOKEN / --management-token: Your required CMA authorization credential.

Scoping (Optional/Experimental)

To restrict the agent's operation strictly to predefined containers, set the following:

SPACE_ID and ENVIRONMENT_ID environment variables (or use --space-id / --environment-id arguments).

When these are configured, the toolset will implicitly use these values, and the space-level discovery tools will be suppressed, as the scope is fixed.

App Identity Authentication

Alternatively, authentication can be managed through Contentful's App Identity framework:

--app-id: Identifier for the registered Contentful App.
--private-key: The private signing key associated with the app ID.
--space-id: The target space ID where the app is installed.
--environment-id: The specific environment within that space.

Using App Identity allows the server to acquire temporary tokens, ideal for backend clients (like autonomous agents) that require secure, scope-limited access.

Integration with Client Platforms (e.g., Claude Desktop)

Direct repository cloning is unnecessary for immediate utilization. Setup can be handled by modifying the client's configuration file (e.g., claude_desktop_config.json):

Method 1: Using Environment Variable Injection

{ "mcpServers": { "contentful": { "command": "npx", "args": ["-y", "@ivotoby/contentful-management-mcp-server"], "env": { "CONTENTFUL_MANAGEMENT_ACCESS_TOKEN": "" } } } }

Method 2: Passing Token via Arguments (If Env Vars are unsupported)

{ "mcpServers": { "contentful": { "command": "npx", "args": ["-y", "@ivotoby/contentful-management-mcp-server", '--management-token', "", '--host', 'http://api.contentful.com'], } } }

Automatic Installation via Smithery

Automated deployment for supported clients can be achieved with:

bash npx -y @smithery/cli install @ivotoby/contentful-management-mcp-server --client claude

Local Development Setup

To test local modifications against the desktop client:

Initiate file watching and server reloading: npm run dev.
Update your client configuration to point directly to the local executable path (e.g., /path/to/contentful-mcp/bin/mcp-server.js).

{ "mcpServers": { "contentful": { "command": "node", "args": ["/path/to/project/bin/mcp-server.js"], "env": { "CONTENTFUL_MANAGEMENT_ACCESS_TOKEN": "" } } } }

(Note: Adding new tool definitions may require a full restart of the client application.)

Robust Error Management

The service incorporates extensive error interception for:

Authentication credential rejections.
API rate limit breaches.
Malformed request payloads.
Underlying network connectivity failures.
Specific errors returned by the Contentful API itself.

Licensing

Distributed under the MIT License.

Critical Warning

This service grants the consuming agent (Claude or similar) the power to alter, remove, and create organizational assets, spaces, and content models. Exercise caution when granting operational permissions to the connected agent, as destructive actions are fully enabled.

WIKIPEDIA CONTEXT (Business Tools): Business management tools encompass the applications, protocols, and systematic approaches employed by organizations to navigate market volatility, maintain competitive footing, and enhance overall operational efficiency. These tools span functional areas such as strategic forecasting, process flow optimization, record-keeping, human capital administration, and control systems. The rapid advancement of technology necessitates a strategic, tailored selection process for these tools, rather than adopting the newest available solution indiscriminately, to ensure alignment with specific organizational objectives.