# Contentrain MCP server

> Manages content governance through deterministic filesystem and git workflows for AI agents and teams.

- Repository: https://github.com/Contentrain/ai
- Page: https://hostedmcp.org/servers/contentrain/contentrain
- Transport: stdio, remote
- Stars: 7
- License: MIT
- Latest version: 3.12.3

## Install

### Claude Code

```sh
claude mcp add contentrain -- npx -y @contentrain/mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "contentrain": {
      "command": "npx",
      "args": [
        "-y",
        "@contentrain/mcp"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "contentrain": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@contentrain/mcp"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"contentrain","type":"stdio","command":"npx","args":["-y","@contentrain/mcp"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "contentrain": {
      "command": "npx",
      "args": [
        "-y",
        "@contentrain/mcp"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add contentrain -- npx -y @contentrain/mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.contentrain]
command = "npx"
args = ["-y", "@contentrain/mcp"]
```

### Gemini CLI

```sh
gemini mcp add -s user contentrain npx -- -y @contentrain/mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "contentrain": {
      "command": "npx",
      "args": [
        "-y",
        "@contentrain/mcp"
      ]
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `CONTENTRAIN_PROJECT_ROOT` | no | no |  |

## Tools (23)

- `contentrain_status`: Get full project status (read-only). Returns config, models, context. Do NOT manually edit .contentrain/ based on this output. (read-only)
- `contentrain_describe`: Get full schema of a single model (read-only). Do NOT manually create content files — use contentrain_content_save instead. (read-only)
- `contentrain_describe_format`: Describes the Contentrain content file format for any language/platform. Returns a comprehensive specification of the file structure, JSON formats, markdown conventions, meta files, and locale strategies. (read-only)
- `contentrain_init`: Initialize .contentrain/ structure. Changes are auto-committed to git — do NOT manually create .contentrain/ files.
- `contentrain_scaffold`: Template-based project setup. Available templates: blog, landing, docs, ecommerce, saas, i18n, mobile. Changes are auto-committed to git.
- `contentrain_model_save`: Create or update a model definition. Changes are auto-committed to git — do NOT manually edit .contentrain/ files after calling this tool.
- `contentrain_model_delete`: Delete a model and its content/meta. Changes are auto-committed to git — do NOT manually edit .contentrain/ files.
- `contentrain_content_save`: Save content entries. Entry format varies by model kind: DICTIONARY — provide "locale" and "data" (flat key-value, all string values); "id" and "slug" are ignored; data keys are the identities. COLLECTION — provide "locale" and "data"; "id" is optional (auto-generated if omitted); "slug" is ignored. DOCUMENT — provide "slug" (required), "locale", and "data"; use the "body" key inside data for markdown content. SINGLETON — provide only "locale" and "data". MEDIA FIELDS (image/video/file): for a media-library asset, pass its storage path ("media/...") or URL; in cloud mode these are automatically normalized to absolute public delivery URLs on save (in markdown bodies too), so saved content renders in a browser anywhere with no SDK — in local mode the relative path is kept as-is. For external images (e.g. a CDN or Unsplash URL), pass the URL directly; it is saved untouched. Changes are auto-committed to git — do NOT manually edit .contentrain/ files after calling this tool.
- `contentrain_content_delete`: Delete content entries. For dictionaries, use "keys" to remove specific keys (omit to delete entire locale file). Changes are auto-committed to git — do NOT manually edit .contentrain/ files after calling this tool.
- `contentrain_content_list`: List content entries (read-only). Each entry carries its publish state under "meta" — status, plus publish_at/expire_at when set — read from the listed locale's meta; singletons and dictionaries carry it at the top level. Local and remote sessions return the same shape. Change status with contentrain_content_status. Returns data from .contentrain/ — do NOT manually create or modify content files. (read-only)
- `contentrain_content_status`: Change the status of content entries — this is how an entry is published, unpublished or archived. Address records the way their meta is laid out: COLLECTION — "entry_ids"; DOCUMENT — "slugs"; SINGLETON and DICTIONARY — neither (one record per locale). i18n models change every supported locale unless "locale" is given. Setting status "published" validates the targeted entries first; if they have errors, nothing is committed. Records already at the requested status are reported as unchanged and not rewritten. contentrain_content_list shows each entry's current status under "meta". Changes are committed to git and follow the project's review or auto-merge workflow — do NOT manually edit .contentrain/meta files.
- `contentrain_vocabulary_save`: Add or update canonical vocabulary terms. Terms nest as { "term-slug": { "en": "…", "tr": "…" } } — the OUTER key is the term, the INNER key is a locale. Merges with the existing vocabulary: a term you omit is untouched. Changes are auto-committed to git — do NOT manually edit .contentrain/vocabulary.json.
- `contentrain_vocabulary_delete`: Remove canonical vocabulary terms by slug. Content already using a term is not touched — the vocabulary only advises. Changes are auto-committed to git.
- `contentrain_validate`: Validate project content against model schemas. Detects required field violations, type mismatches, broken relations, secret leaks, i18n parity issues, and more. If fix:true, auto-fixes structural issues (canonical sort, orphan meta, missing locale files, stray non-i18n meta layout, scheduling keys an older content_save leaked into document frontmatter) and backfills a missing model title_field — do NOT manually edit .contentrain/ files. Content without meta gets meta with status published, matching what delivery already serves. A fix that would change whether an entry is delivered is listed in visibility_changes and left on its branch for review instead of auto-merged.
- `contentrain_submit`: Push cr/* branches to remote. MCP is push-only — PR creation is handled by the platform. Do NOT manually push or create PRs.
- `contentrain_merge`: Merge a review-mode branch into contentrain. Local git operation — no external platform needed. Merges the feature branch into the contentrain branch, advances the base branch via update-ref, selectively syncs .contentrain/ files to the working tree, and prunes the merged branch. Target by exact "branch" name, or resolve by "model" (+ optional "locale"/"latest").
- `contentrain_branch_list`: List pending contentrain (cr/*) branches with their merge status against the contentrain branch. Use this to discover branch names for contentrain_merge / contentrain_branch_delete, and to monitor branch-health limits (warning at 50, blocked at 80 unmerged). (read-only)
- `contentrain_branch_delete`: Delete a pending contentrain (cr/*) branch that will not be merged — e.g. a branch left behind by a failed operation, or a superseded draft. Only cr/* branches can be deleted; the contentrain branch is protected. This is destructive: the branch and its unmerged commits are removed.
- `contentrain_reconcile`: Reconcile a diverged contentrain ↔ base-branch pair with a content-aware three-way merge. DRY RUN (default, dry_run:true): reports what would merge and which conflicts need a decision — touches nothing. EXECUTE (dry_run:false): performs the merge as a two-parent commit on contentrain and fast-forwards the base branch. Everything one side changed merges mechanically (entry-, key-, term+locale-level); only the same item changed differently on both sides becomes a conflict. Answer conflicts by passing resolutions (from the dry-run ids) and running again — a resolution whose values changed since the dry-run is dropped and the conflict re-reported. Recommended workflow: always run dry_run first, review the summary and conflicts, then execute.
- `contentrain_scan`: Scan project source code for content strings. Three modes: "graph" builds import/component graph for project intelligence, "candidates" extracts string literals with pre-filtering and pagination, "summary" provides quick overview stats. Read-only — no changes to disk or git. MCP finds strings deterministically; the agent decides what is content. Recommended workflow: start with "summary" or "graph" for orientation, then paginate through "candidates" to evaluate strings. (read-only)
- `contentrain_apply`: Apply normalize operations. Two modes: "extract" writes agent-approved strings to Contentrain content files (source untouched), "reuse" patches source files with agent-provided replacement expressions. DRY RUN (default, dry_run:true): validates inputs, resolves conflicts, and returns a full preview — NO changes to disk or git. EXECUTE (dry_run:false): writes files to disk, commits to a branch, and requires branch health check to pass. Recommended workflow: always run dry_run first, review the preview, then call again with dry_run:false to execute. Normalize operations always use review workflow (never auto-merge).
- `contentrain_bulk`: Batch operations on content entries: copy a locale, or delete many collection entries. All operations are auto-committed to git. To publish or change status, use contentrain_content_status. DRY RUN (dry_run:true): runs the whole operation in a throwaway worktree and reports exactly what would change — nothing is committed and no branch survives. Recommended workflow: preview with dry_run:true, review the counts, then call again to execute.
- `contentrain_doctor`: Project health report (read-only). Returns structured checks: git, node, .contentrain/ structure, model parse, orphan content, branch pressure, SDK freshness. Pass `usage: true` for a deeper analysis of content-key references in source files (unused keys, duplicate dictionary values, locale coverage). Local-filesystem only — unavailable over remote providers. (read-only)

## FAQ

### How does Contentrain ensure write safety?

All write operations use a git-backed safety model where each write creates a temporary worktree on a dedicated feature branch.
