MCP HubMCP Hub
ivo-toby

contentful-mcp

by: ivo-toby

MCP (Model Context Protocol) server for the Contentful Management API

27created 04/12/2024
Visit
Contentful
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

  1. Create a Contentful account at https://www.contentful.com/
  2. 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 and ENVIRONMENT_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.