Contentful Management Protocol Server Implementation

Important Notification

This utility represents a community-developed solution! Contentful has also made available an official server implementation, which can be accessed here.

This is a specialized MCP server adapter built to interface with the Contentful Content Management API, furnishing extensive content governance features.

• Usage Note: If your objective is solely to employ this MCP within Claude Desktop (or any compatible MCP client) without needing source code access, you can bypass repository cloning. Installation instructions are detailed in the "Integration with Claude Desktop" section below.

Core Capabilities

• Content Governance: Comprehensive Create, Read, Update, Delete (CRUD) functionalities for both content entries and digital assets.
• Annotation Management: Ability to generate, fetch, and manage annotations attached to entries, supporting both plain text and rich text formats, including nested conversation structures.
• Workspace Configuration: Tools for provisioning, modifying, and administering Contentful spaces and their respective environments.
• Schema Definition: Management utilities for content type blueprints.
• Multilingual Support: Native compatibility with multiple locales for localized content.
• Deployment Control: Fine-grained command over the content publishing lifecycle.
• Batch Processing: Execution of large-scale publication, withdrawal, and validation actions across numerous content items.
• Intelligent Paging: Listing operations are capped at a maximum of 3 records per invocation to safeguard the LLM's context window integrity, complete with integrated mechanisms for fetching subsequent pages.

Context Window Safeguard (Pagination Details)

To mitigate potential overflow within Large Language Model context windows, retrieval commands (such as search_entries and list_assets) are restricted to returning a maximum of three items per call. Each response package contains:

• The total aggregate count of accessible items.
• The current subset of items (limited to 3).
• The quantity of remaining records.
• The requisite 'skip' offset for initiating the subsequent query.
• A directive encouraging the LLM to request further data if necessary.

This structured paging system ensures efficient data retrieval and processing, even with substantial data volumes, while respecting operational context limits.

Batch Operations Utility

The capability for batch operations enables efficient simultaneous modification of multiple content resources:

• Asynchronous Execution: Operations initiate in the background, supplying periodic progress reports.
• Streamlined Management: Process numerous entries or assets within a singular API transaction.
• Progress Oversight: Detailed monitoring of completion status, including success and failure tallies.
• Performance Enhancement: Reduction in redundant API calls, leading to superior throughput for batch workflows.

These batch tooling functionalities are optimal for large-scale content transitions, mass attribute updates, or coordinated publishing campaigns.

Available Tools

Entry Manipulation

• search_entries: Query entries based on supplied parameters.
• create_entry: Provision new content records.
• get_entry: Retrieve details of an existing content record.
• update_entry: Modify the fields of a content record.
• delete_entry: Permanently eliminate content records.
• publish_entry: Deploy content records to the live environment.
• unpublish_entry: Withdraw deployed content records.

Annotation Services

• get_comments: Fetch annotations linked to an entry, filterable by status (active, resolved, all).
• create_comment: Initiate new annotations on entries (supports both plain and rich text). Facilitates nested discussions via the parent ID parameter to form replies.
• get_single_comment: Fetch a singular annotation using its unique identifier.
• delete_comment: Erase a specific annotation.
• update_comment: Revise the body content or status of an existing annotation.

Nested Annotation Structure

Annotations support hierarchical threading to facilitate structured dialogue and circumvent potential length restrictions:

• Reply Functionality: Utilize the parent argument within create_comment to directly reference an existing annotation for a reply.
• Conversation Trees: Construct multi-level discussion structures by replying to specific annotations within the thread.
• Extended Dialogue: Circumvent typical message size constraints by initiating follow-up replies within an established thread.
• Contextual Integrity: Preserve discussion context by organizing related annotations into distinct threads.

Usage Sequence Example:

1. Establish a primary annotation: Invoke create_comment with entryId, body, and status.
2. Respond to the primary annotation: Call create_comment including entryId, body, status, and the parent ID of the target comment.
3. Continue the chain: Reply to any annotation within the thread by referencing its ID as the parent parameter.

Batch Processing Tools

• bulk_publish: Initiate publication for numerous entries and assets in one transaction. Accepts an array of targets for batch deployment.
• bulk_unpublish: Withdraw multiple entries and assets simultaneously. Functions identically to bulk_publish but targets removal from the delivery API.
• bulk_validate: Assess multiple entries for adherence to schema rules, reference integrity, and mandatory field presence. Returns diagnostic results without altering content.

Asset Management

• list_assets: Retrieve a paginated directory of assets (3 per page).
• upload_asset: Introduce new assets along with their descriptive metadata.
• get_asset: Fetch detailed information about a specific asset.
• update_asset: Modify both the descriptive metadata and the file content of an asset.
• delete_asset: Remove assets from the current space.
• publish_asset: Make assets available via the delivery API.
• unpublish_asset: Withdraw assets from delivery API access.

Space and Environment Administration

• list_spaces: Enumerate all accessible Contentful spaces.
• get_space: Retrieve configuration details for a specific space.
• list_environments: List all defined environments within a space.
• create_environment: Provision a new isolated environment.
• delete_environment: Decommission an existing environment.

Content Type Schema Tools

• list_content_types: Fetch definitions of existing content schemas.
• get_content_type: Retrieve the blueprint details for a schema.
• create_content_type: Define and register a new content schema.
• update_content_type: Modify an existing content schema definition.
• delete_content_type: Remove a content schema.
• publish_content_type: Deploy a content schema for live usage.

Development Support Utilities

MCP Inspector Console

The development package incorporates an MCP Inspector utility designed to aid in testing and debugging:

• Inspection Mode: Execute npm run inspect to initialize the inspector interface, accessible via http://localhost:5173.
• Live Reloading: Use npm run inspect:watch for automatic inspector restart upon source code modification.
• Graphical Interface: The inspector provides a web-based environment for tool interaction and debugging.
• Immediate Feedback: Test tool invocations and instantly view the returned results.
• Batch Testing Visualization: Monitor the progression and final outcomes of bulk operations visually.

The repository also includes the npm run dev command, configured to trigger a complete rebuild and reload of the MCP server whenever source files are altered.

Setup and Environment Configuration

Pre-requisites

1. Secure a Contentful account via Contentful.
2. Generate a valid Content Management API access token within your account settings.

Environment Variables / Command Arguments

These settings can be defined via environment variables or passed directly as command-line flags:

• CONTENTFUL_HOST / --host: The base URL for the Contentful Management API (defaults to https://api.contentful.com).
• CONTENTFUL_MANAGEMENT_ACCESS_TOKEN / --management-token: Your requisite Content Management API credential.
• ENABLE_HTTP_SERVER / --http: Set value to "true" to activate the HTTP/SSE communication modality.
• HTTP_PORT / --port: The network port allocated for the HTTP server (default is 3000).
• HTTP_HOST / --http-host: The network interface binding for the HTTP server (default is localhost).

Scoping to Specific Spaces/Environments

Space and Environment identifiers can be hardcoded to restrict the LLM's scope, ensuring operations only affect designated containers. If both SPACE_ID and ENVIRONMENT_ID are set via environment variables, the tools will bypass requests for these values, utilizing the fixed configuration instead. Note that this scoping might restrict access to tools designed for cross-space operations.

These identifiers can also be supplied via arguments: --space-id and --environment-id.

Utilizing App Identity Authentication

As an alternative to using a direct Management Token, authentication can be managed through Contentful App Identity. This necessitates setting up and installing a Contentful Application and supplying the subsequent parameters when launching the MCP server:

• --app-id: The identifier for the application generating the Apptoken.
• --private-key: The private key generated in the application interface, linked to the app_id.
• --space-id: The identifier of the space where the application is installed.
• --environment-id: The identifier of the environment (within the space) where the application is installed.

These parameters enable the MCP server to dynamically fetch a temporary AppToken, facilitating content manipulation within the specified space/environment. This method is particularly advantageous for backend services acting as MCP clients (e.g., autonomous agents).

Integration with Claude Desktop

Cloning this repository is unnecessary for basic Claude Desktop usage. The adapter can be configured directly within your claude_desktop_config.json file:

Modify or create ~/Library/Application Support/Claude/claude_desktop_config.json and incorporate the following section:

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

If your MCP client lacks the capability to inject environment variables, the management token can be supplied via command-line arguments:

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

Automated Installation via Smithery

To automate the setup of the Contentful Management Server for Claude Desktop using Smithery:

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

Local Development and Testing with Claude Desktop

For developers wishing to test local modifications directly with Claude:

• Execute npm run dev. This initiates a watcher process that triggers server recompilation upon any file change.
• Update claude_desktop_config.json to point directly to the project's executable file. For example (adjust path as necessary):

{
  "mcpServers": {
    "contentful": {
      "command": "node",
      "args": ["/Users/ivo/workspace/contentful-mcp/bin/mcp-server.js"],
      "env": {
        "CONTENTFUL_MANAGEMENT_ACCESS_TOKEN": "<Your CMA Token>"
      }
    }
  }
}

This setup enables immediate testing of server modifications within Claude. However, adding new tools or resources may necessitate a subsequent restart of the Claude Desktop application.

Communication Protocols

The MCP server is engineered to support two distinct modes of data transmission:

Standard I/O Transport (stdio)

This is the default operational mode, utilizing standard input and output streams for all communication. It is optimized for clients designed to interface via stdio, such as Claude Desktop.

To activate stdio mode, launch the server without specifying the --http parameter:

npx -y contentful-mcp --management-token YOUR_TOKEN
# OR alternatively
npx -y @ivotoby/contentful-management-mcp-server --management-token YOUR_TOKEN

Streamable HTTP Transport

The server also implements the StreamableHTTP transport method specified within the MCP protocol. This mode is advantageous when deploying the server as a distinct web service or integrating with web-based clients.

Activate StreamableHTTP mode by including the --http argument:

npx -y contentful-mcp --management-token YOUR_TOKEN --http --port 3000
# OR alternatively
npx -y @ivotoby/contentful-management-mcp-server --management-token YOUR_TOKEN --http --port 3000

StreamableHTTP Specifications

• Adheres strictly to the official MCP StreamableHTTP transport specification.
• Supports all mandated MCP operational commands.
• Incorporates mechanisms for session state persistence.
• Correctly implements the initialize/notify messaging patterns.
• Fully compatible with conventional MCP client software.
• Represents a modern replacement for the deprecated Server-Sent Events (SSE) transport mechanism.

The underlying architecture complies with the formal MCP protocol documentation, ensuring universal connectivity for any client adhering to the standard.

Error Management System

The server features robust handling for common failure scenarios, including:

• Authentication token invalidation or denial.
• Exceeding API rate limits.
• Malformed request payloads.
• Connectivity disruptions.
• Contentful API-specific error responses.

Licensing

Licensed under the MIT License.

Crucial Disclaimer

This MCP Server grants agents (like Claude or others capable of utilizing MCP resources) the authority to modify, eradicate content, alter space settings, and manage content blueprints. Exercise caution regarding the permissions conferred upon the agent operating against your Contentful environments!

This MCP server is currently not an officially endorsed product by Contentful (as of this documentation).

WIKIPEDIA: XMLHttpRequest (XHR) refers to an application programming interface, structured as a JavaScript object, whose methods facilitate the transmission of HTTP requests from a web browser to an intermediary web server. These methods allow client-side applications to dispatch requests post-page load and receive subsequent data. XMLHttpRequest forms a core component of Ajax programming paradigms. Before Ajax gained prominence, the primary means of server interaction involved traditional page reloads triggered by hyperlinks or form submissions. The methods allow a browser-based application to send requests to the server after page loading is complete, and receive information back. XMLHttpRequest is a component of Ajax programming. Prior to Ajax, hyperlinks and form submissions were the primary mechanisms for interacting with the server, often replacing the current page with another one.

== Historical Development == The conceptual foundation for XMLHttpRequest was first devised in 2000 by engineers associated with Microsoft Outlook development. This concept was subsequently integrated into the Internet Explorer 5 browser (released in 1999). However, the initial syntax did not utilize the specific identifier XMLHttpRequest. Instead, developers relied on instantiating objects via ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). By the release of Internet Explorer 7 (2006), all dominant browsers had standardized support for the XMLHttpRequest identifier. The XMLHttpRequest identifier has since become the established convention across all major browser engines, including Mozilla's Gecko rendering platform (2002), Apple's Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) issued its initial Working Draft specification for the XMLHttpRequest object on April 5, 2006. On February 25, 2008, the W3C published the subsequent Working Draft Level 2 specification. Level 2 introduced enhancements such as methods for monitoring transfer progress, enabling cross-site data exchange, and managing raw byte streams. By the close of 2011, the Level 2 features were formally merged back into the primary specification. At the conclusion of 2012, the development stewardship transferred to the WHATWG, which now maintains a continuously evolving document leveraging Web IDL definitions.

== Practical Application == Generally, executing a data request using XMLHttpRequest necessitates adherence to several sequential programming stages.

1. Instantiate an XMLHttpRequest object by invoking its constructor:
2. Invoke the `open" method to define the request methodology, specify the target resource URI, and select between synchronous or asynchronous execution:
3. For asynchronous transmissions, establish an event handler callback that is triggered upon state transitions in the request lifecycle:
4. Commence the data transmission by calling the `send" method:
5. Process the incoming response data within the designated event listener. If the server successfully returns data, it is typically consolidated in the responseText attribute by default. When the object finalizes processing the response, its state transitions to 4, signifying the "done" condition. Beyond these fundamental procedures, XMLHttpRequest offers numerous parameters to control request transmission behaviors and response handling. Custom HTTP headers can be appended to tailor server fulfillment logic, and data payload can be transmitted to the server via the argument provided to the `send" call. The incoming response can be parsed instantly from JSON format into a native JavaScript object structure, or processed iteratively as chunks arrive, rather than waiting for the complete textual body. Furthermore, the request can be terminated prematurely or configured with a timeout threshold.

== Inter-domain Communication == During the nascent phase of the World Wide Web, it was observed that restrictions could be easily bypassed, leading to security vulnerabilities regarding cross-origin data exchange. The methods allow a browser-based application to send requests to the server after page loading is complete, and receive information back. XMLHttpRequest is a component of Ajax programming. Prior to Ajax, hyperlinks and form submissions were the primary mechanisms for interacting with the server, often replacing the current page with another one.