@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