@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 17 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

Diagnostics

Tool	Description
contentrain_doctor	Full diagnostic scan — detects ID, schema, relation, asset, and sync issues. Use fix=true to auto-repair (pushes to a staging branch for review).
contentrain_doctor_apply	Merge a staged doctor fix into the target branch
contentrain_doctor_discard	Discard a staged doctor fix without merging

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:

1. Creates an isolated git worktree from the target branch
2. Applies all changes inside the worktree
3. Commits and pushes to the target branch
4. 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)
5. 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