README.md•14.1 kB
# Contentful MCP Server
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that provides AI assistants with comprehensive tools to interact with [Contentful](https://www.contentful.com/) APIs.
## 🚀 Example Use Cases
This MCP server provides a comprehensive set of tools for content management, allowing AI to help you create, edit, organize, and publish content directly within Contentful. Once configured, you can use natural language in your AI assistant of choice to manage and interact with your Contentful spaces, including:
- **Content Creation**: "Create a new blog post for our fall product launch"
- **Content Management**: "Update all product entries to include the new pricing structure"
- **Asset Organization**: "Upload and organize these marketing images by campaign"
- **Workflow Automation**: "Create an AI action that translates content to Spanish"
- **Content Modeling**: "Add a new field to the product content type for customer ratings"
## 📓 Table of Contents
- [⚙️ Getting Started](#-getting-started)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Environment Variables](#environment-variables)
- [Configuration](#configuration)
- [🛠️ Available Tools](#️-available-tools)
- [🔍 Development](#-development)
- [Testing with MCP Inspector](#testing-with-mcp-inspector)
- [Linting](#linting)
- [📦 Releases](#-releases)
- [🤝 Contributing](#-contributing)
- [Development Setup](#development-setup)
- [📚 Documentation](#-documentation)
- [❓ Help & Support](#-help--support)
- [📄 License and Notices](#-license-and-notices)
- [🛡️ Code of Conduct](#️-code-of-conduct)
## ⚙️ Getting started
### Prerequisites
- Node.js
- npm
- A Contentful account with a [Space ID](https://www.contentful.com/help/spaces/find-space-id/)
- [Contentful Management API personal access token](https://www.contentful.com/help/token-management/personal-access-tokens/)
### Installation
#### One-Click install
[](https://cursor.com/en/install-mcp?name=contentful-mcp&config=eyJjb21tYW5kIjoibnB4IC15IEBjb250ZW50ZnVsL21jcC1zZXJ2ZXIiLCJlbnYiOnsiQ09OVEVOVEZVTF9NQU5BR0VNRU5UX0FDQ0VTU19UT0tFTiI6InlvdXItQ01BLXRva2VuIiwiU1BBQ0VfSUQiOiJ5b3VyLXNwYWNlLWlkIiwiRU5WSVJPTk1FTlRfSUQiOiJtYXN0ZXIiLCJDT05URU5URlVMX0hPU1QiOiJhcGkuY29udGVudGZ1bC5jb20ifX0%3D)
_Note: This requires [Cursor](https://cursor.com/) to be installed. If the link doesn't work, try the manual installation below._
**Claude Desktop:**
Download the .dxt configuration file [here](https://github.com/contentful/contentful-mcp-server/releases) from the latest release and import it into Claude Desktop to automatically configure the MCP server with your environment variables.
#### Install from source
```bash
git clone https://github.com/contentful/contentful-mcp-server.git
cd contentful-mcp-server
npm install
npm run build
```
### Environment Variables
| Environment Variable | Required | Default Value | Description |
| ------------------------------------ | -------- | -------------------- | ---------------------------------------------------- |
| `CONTENTFUL_MANAGEMENT_ACCESS_TOKEN` | ✅ Yes | - | Your Contentful Management API personal access token |
| `SPACE_ID` | ✅ Yes | - | Your Contentful Space ID |
| `ENVIRONMENT_ID` | ❌ No | `master` | Target environment within your space |
| `CONTENTFUL_HOST` | ❌ No | `api.contentful.com` | Contentful API host |
| `NODE_ENV` | ❌ No | `production` | Node Environment to run in |
### Configuration
Refer to the documentation for your AI tool of choice for how to configure MCP servers. For example, see the documentation for [Cursor](https://docs.cursor.com/context/mcp), [VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers), or [Claude Desktop](https://modelcontextprotocol.io/quickstart/user).
Below is a sample configuration:
```json
{
"mcpServers": {
"contentful-mcp": {
"command": "npx",
"args": ["-y", "@contentful/mcp-server"],
"env": {
"CONTENTFUL_MANAGEMENT_ACCESS_TOKEN": "your-CMA-token",
"SPACE_ID": "your-space-id",
"ENVIRONMENT_ID": "master",
"CONTENTFUL_HOST": "api.contentful.com"
}
}
}
}
```
## 🛠️ Available Tools
| Category | Tool Name | Description |
| ------------------------- | ---------------------------------- | ------------------------------------------------ |
| **Context & Setup** | `get_initial_context` | Initialize connection and get usage instructions |
| **Content Types** | `list_content_types` | List content types (max 10 per request) |
| | `get_content_type` | Get detailed content type information |
| | `create_content_type` | Create new content types |
| | `update_content_type` | Modify existing content types |
| | `publish_content_type` | Publish content type changes |
| | `unpublish_content_type` | Unpublish content types |
| | `delete_content_type` | Remove content types |
| **Entries** | `search_entries` | Search and filter entries in your space |
| | `get_entry` | Retrieve specific entries |
| | `create_entry` | Create new content entries with locale support |
| | `update_entry` | Modify existing entries with locale support |
| | `publish_entry` | Publish entries (single or bulk up to 100) |
| | `unpublish_entry` | Unpublish entries (single or bulk up to 100) |
| | `delete_entry` | Remove entries |
| **Editor Interfaces** | `list_editor_interfaces` | List all editor interfaces in a space |
| | `get_editor_interface` | Get editor interface for a content type |
| | `update_editor_interface` | Update field controls, sidebars, and layouts |
| **Assets** | `upload_asset` | Upload new assets |
| | `list_assets` | List and browse assets (max 3 per request) |
| | `get_asset` | Retrieve specific assets |
| | `update_asset` | Modify asset metadata |
| | `publish_asset` | Publish assets (single or bulk up to 100) |
| | `unpublish_asset` | Unpublish assets (single or bulk up to 100) |
| | `delete_asset` | Remove assets |
| **Spaces & Environments** | `list_spaces` | List available spaces (max 10 per request) |
| | `get_space` | Get space details |
| | `list_environments` | List environments in a space |
| | `create_environment` | Create new environments |
| | `delete_environment` | Remove environments |
| **Locales** | `list_locales` | List all locales in your environment |
| | `get_locale` | Retrieve specific locale information |
| | `create_locale` | Create new locales for multi-language content |
| | `update_locale` | Modify existing locale settings |
| | `delete_locale` | Remove locales from environment |
| **Tags** | `list_tags` | List all tags in an environment |
| | `create_tag` | Create new tags with public/private visibility |
| **Organizations** | `list_orgs` | List organizations user has access to |
| | `get_org` | Get details of a specific organization |
| **AI Actions** | `create_ai_action` | Create custom AI-powered workflows |
| | `invoke_ai_action` | Invoke AI action with variables (bulk support) |
| | `get_ai_action_invocation` | Get AI action invocation details |
| | `get_ai_action` | Retrieve AI action details and configuration |
| | `list_ai_actions` | List AI actions in a space (max 3 per request) |
| | `update_ai_action` | Update existing AI actions |
| | `publish_ai_action` | Publish AI actions for use |
| | `unpublish_ai_action` | Unpublish AI actions |
| | `delete_ai_action` | Remove AI actions |
| **Taxonomy Concepts** | `create_concept` | Create new taxonomy concepts with localization |
| | `get_concept` | Retrieve specific taxonomy concept |
| | `list_concepts` | List concepts with filtering and hierarchy |
| | `update_concept` | Update taxonomy concept properties |
| | `delete_concept` | Remove taxonomy concepts |
| **Taxonomy Schemes** | `create_concept_scheme` | Create new taxonomy concept schemes |
| | `get_concept_scheme` | Retrieve specific concept scheme |
| | `list_concept_schemes` | List concept schemes with pagination |
| | `update_concept_scheme` | Update concept scheme properties |
| | `delete_concept_scheme` | Remove concept schemes |
| **Space Migration** | `space_to_space_migration_handler` | Enable/disable space migration workflow |
| | `space_to_space_param_collection` | Collect parameters for migration workflow |
| | `export_space` | Export space to file for migration |
| | `import_space` | Import space from exported file |
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for local development setup and contribution guidelines.
## 📦 Releases
This project uses [Nx Release](https://nx.dev/features/manage-releases) for automated versioning and publishing. Releases are automatically generated based on [Conventional Commits](https://www.conventionalcommits.org/). See [Contributing Guide](CONTRIBUTING.md) for more information on release process.
## 📚 Documentation
- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
- [Contentful Management API Documentation](https://www.contentful.com/developers/docs/references/content-management-api/)
## ❓ Help & Support
- [Contentful support resources](https://www.contentful.com/help/getting-started/how-to-get-help/)
- [Report bugs or request features](https://github.com/contentful/contentful-mcp-server/issues)
- [Contentful Community Discord](https://www.contentful.com/discord/)
## 📄 License and Notices
This project is licensed under the MIT License. See [LICENSE](./LICENSE) for details.
It also includes open-source components licensed under MIT, BSD-2-Clause, and Apache-2.0. For details, see the [NOTICE](./NOTICE) file.
This project includes an automated license management system that keeps track of all dependencies and their licenses. See the [AUTOMATION-FOR-LICENSES](./AUTOMATION-FOR-LICENSES.md) file for more information.
## 🛡️ Code of Conduct
We want to provide a safe, inclusive, welcoming, and harassment-free space and experience for all participants, regardless of gender identity and expression, sexual orientation, disability, physical appearance, socioeconomic status, body size, ethnicity, nationality, level of experience, age, religion (or lack thereof), or other identity markers.
[Read our full Code of Conduct](https://www.contentful.com/developers/code-of-conduct/).