Which integrations are available for this server?

Provides automated git operations including branch synchronization, commits, and structural 3-way merges to manage content within a git-based headless CMS. Integrates with GitHub repositories to manage Contentrain CMS projects, ensuring content changes are automatically synchronized with the remote repository. Allows for the management of Contentrain models and content entries using Markdown, supporting the creation and update of localized content through a standardized protocol. Supports the management of Contentrain models and content using the MDX format, enabling AI agents to handle rich content creation and schema management.

How do I use Contentrain MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Contentrain MCP Server Create a draft blog post titled 'Getting Started' in English" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

@contentrain/mcp

MCP (Model Context Protocol) server for Contentrain CMS content management. Enables AI agents (Claude, Codex, Cursor, etc.) and humans to create, read, update, and delete Contentrain models, content, and assets — with automatic git branch synchronization.

Why?

Contentrain is a git-based headless CMS. This MCP server lets AI assistants directly manage your Contentrain content through a standardized protocol, so you can say things like:

"Create a blog post model with title, excerpt, and cover image fields"
"Add a new blog post in English and Turkish"
"List all FAQ entries and update the second one"

All changes are committed and pushed to your git repository automatically.

Prerequisites

A Contentrain project already set up via the Contentrain Web App
The project's GitHub repository cloned locally
Node.js >= 18

Important: Contentrain projects must be initialized through the Web App first. The Web App creates the repository structure, the contentrain branch, models, and environment configuration. This MCP server operates on an existing Contentrain project — it does not replace the initial setup.

Quick Start

1. Install

# From npm (when published)
npm install -g @contentrain/mcp

# Or from source
git clone https://github.com/Contentrain/contentrain-mcp.git
cd contentrain-mcp
pnpm install && pnpm build

2. Configure your MCP client

Add to your MCP client configuration:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "contentrain": {
      "command": "contentrain-mcp",
      "env": {
        "CONTENTRAIN_REPO_PATH": "/path/to/your/contentrain-project",
        "CONTENTRAIN_BRANCH": "contentrain"
      }
    }
  }
}

Cursor (.cursor/mcp.json in your project root):

{
  "mcpServers": {
    "contentrain": {
      "command": "contentrain-mcp",
      "env": {
        "CONTENTRAIN_REPO_PATH": "/path/to/your/contentrain-project",
        "CONTENTRAIN_BRANCH": "contentrain"
      }
    }
  }
}

Claude Code (.mcp.json in your project root):

{
  "mcpServers": {
    "contentrain": {
      "command": "contentrain-mcp",
      "env": {
        "CONTENTRAIN_REPO_PATH": "/path/to/your/contentrain-project",
        "CONTENTRAIN_BRANCH": "contentrain"
      }
    }
  }
}

If installed from source instead of globally, replace "command": "contentrain-mcp" with "command": "node" and add "args": ["/absolute/path/to/contentrain-mcp/dist/index.mjs"].

3. Start using

Once configured, your AI assistant has access to 14 tools. Here's an example conversation:

You:    List all my models
Agent:  → calls contentrain_list_models
        You have 3 models: blog (MD, localized), faq (JSON), authors (JSON)

You:    Show me the blog model schema
Agent:  → calls contentrain_describe_model { modelId: "blog" }
        Blog model has fields: title (string, required), description (string),
        category (one-to-one → blogcategories), imagesrc (media), author (one-to-one → authors)

You:    Create a new blog post titled "Getting Started with Contentrain"
Agent:  → calls contentrain_create_content {
            modelId: "blog",
            data: { title: "Getting Started with Contentrain", slug: "getting-started-with-contentrain", description: "..." },
            locale: "en",
            status: "draft",
            content: "# Getting Started\n\nWelcome to Contentrain..."
          }
        Created entry e7f3a1b9c0d2 in blog model (draft).
        Committed and pushed to contentrain branch.

You:    Now publish it
Agent:  → calls contentrain_update_content {
            modelId: "blog",
            entryId: "e7f3a1b9c0d2",
            data: { status: "publish" },
            locale: "en"
          }
        Updated and published.

Environments

Contentrain uses git branches to manage environments. Each environment maps to a branch:

Environment	Branch	Description
Default	`contentrain`	Main content branch (created automatically)
Staging	`contentrain-staging`	Preview/staging environment
Production	`contentrain-production`	Production environment

Environments are created via the Contentrain Web App. The branch naming follows the pattern contentrain-{environment-name}.

Targeting a specific environment

Set the CONTENTRAIN_BRANCH environment variable to the target environment's branch:

{
  "mcpServers": {
    "contentrain": {
      "command": "contentrain-mcp",
      "env": {
        "CONTENTRAIN_REPO_PATH": "/path/to/project",
        "CONTENTRAIN_BRANCH": "contentrain-staging"
      }
    }
  }
}

Multiple environments simultaneously

You can register multiple MCP server instances — one per environment:

{
  "mcpServers": {
    "contentrain-default": {
      "command": "contentrain-mcp",
      "env": {
        "CONTENTRAIN_REPO_PATH": "/path/to/project",
        "CONTENTRAIN_BRANCH": "contentrain"
      }
    },
    "contentrain-staging": {
      "command": "contentrain-mcp",
      "env": {
        "CONTENTRAIN_REPO_PATH": "/path/to/project",
        "CONTENTRAIN_BRANCH": "contentrain-staging"
      }
    }
  }
}

Available Tools

Model Management

Tool	Description
`contentrain_list_models`	List all models with metadata
`contentrain_describe_model`	Get full schema with field definitions
`contentrain_create_model`	Create a new model (JSON, MD, or MDX)
`contentrain_add_field`	Add a field to an existing model
`contentrain_delete_model`	Delete a model and all its content

Content Management

Tool	Description
`contentrain_list_content`	List all entries for a model
`contentrain_get_content`	Get a single entry by ID
`contentrain_create_content`	Create a new entry with validation
`contentrain_update_content`	Update specific fields of an entry
`contentrain_delete_content`	Delete an entry (all locales + markdown)
`contentrain_validate`	Dry-run validation against model schema

Asset Management

Tool	Description
`contentrain_list_assets`	List all registered assets
`contentrain_register_asset`	Register an existing file as an asset
`contentrain_deregister_asset`	Remove an asset from the registry

Environment Variables

Variable	Default	Description
`CONTENTRAIN_REPO_PATH`	`process.cwd()`	Path to the git repository
`CONTENTRAIN_BRANCH`	`contentrain`	Target environment branch
`CONTENTRAIN_REMOTE`	`origin`	Git remote name
`CONTENTRAIN_DIR`	`contentrain`	Contentrain directory name
`CONTENTRAIN_DRY_RUN`	`false`	Skip git operations (local changes only)
`CONTENTRAIN_AUTHOR_NAME`	—	Git commit author name
`CONTENTRAIN_AUTHOR_EMAIL`	—	Git commit author email

Programmatic Usage

You can also use the writer directly in your own code:

import { ContentrainWriter } from '@contentrain/mcp'

const writer = new ContentrainWriter({
  repoPath: '/path/to/your/project',
  branch: 'contentrain',
})

// Read operations (no git transaction needed)
const models = await writer.model.list()
const entries = await writer.content.list('blog-posts')

// Write operations (uses git worktree + commit + push)
await writer.transaction(async (tx) => {
  await tx.content.create('blog-posts', {
    title: 'Hello World',
    excerpt: 'My first post',
  }, { status: 'draft' })
}, { message: 'add new blog post' })

How Git Sync Works

Every write operation runs inside a transaction:

Creates an isolated git worktree from the target branch
Applies all changes inside the worktree
Commits and pushes to the target branch
If the push is rejected (remote advanced), performs a structural 3-way merge — diffing JSON entries by their ID field instead of text lines — then retries (up to 3 attempts)
Cleans up the worktree

This means concurrent writes from multiple agents or the Contentrain web app won't conflict.

Development

pnpm install        # Install dependencies
pnpm dev            # Watch mode build
pnpm test           # Run tests (watch mode)
pnpm test:run       # Run tests once
pnpm lint           # Lint with oxlint
pnpm build          # Production build

License

MIT

Contentrain MCP Server