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

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

Content Management

Asset Management

Diagnostics

Environment Variables

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