The open-source AI Content Engine.
Markdown-first. Three interfaces, one data layer.

Quick Start · Self-Hosting · Docs · Roadmap · Contributing

---

What is MDCMS?

An open-source CMS that's Markdown-first. Import your existing project in minutes, edit in a collaborative Studio, and let AI agents work with your content at scale.

Developers define schemas in code and sync via CLI. Editors get a visual Studio they never have to leave. AI agents process content through the same API. Nobody waits for someone else.

mdcms pull to work on files locally, mdcms push to sync them back. Same editing experience as local files, but the content lives outside your repo. Update a typo without triggering a rebuild. Have five editors on the same page without merge conflicts.

Demo

mdcms-demo.mp4

Quick Start

Using an AI coding agent? Run npx skills add Blazity/mdcms to install the MDCMS Skills Pack — your agent will walk through the setup below for you. Supports Claude Code, Cursor, Gemini CLI, Codex, Copilot, and 40+ others via skills.sh.

1. Install packages

npm install @mdcms/cli @mdcms/sdk

2. Define your content schema

Create a mdcms.config.ts in your project root:

import { defineConfig, defineType } from "@mdcms/cli";
import { z } from "zod";

export default defineConfig({
  project: "my-site",
  environment: "production",
  serverUrl: "https://your-mdcms-server.example.com",
  contentDirectories: ["content"],
  types: [
    defineType("BlogPost", {
      directory: "content/blog",
      fields: {
        title: z.string().min(1),
        summary: z.string().optional(),
      },
    }),
  ],
});

3. Pull and push content

# Authenticate with your MDCMS server
npx mdcms login

# Pull content to local Markdown files
npx mdcms pull

# Edit your .md or .mdx files, then push changes back
npx mdcms push

4. Fetch content in your app

import { createClient } from "@mdcms/sdk";

const cms = createClient({
  serverUrl: "https://your-mdcms-server.example.com",
  apiKey: process.env.MDCMS_API_KEY!,
  project: "my-site",
  environment: "production",
});

const posts = await cms.list("BlogPost", { locale: "en", published: true });

Embed the Studio UI (optional)

Add a visual editing interface to your app:

npm install @mdcms/studio

See the @mdcms/studio README for embedding instructions.

Self-Hosting

Run your own MDCMS server with Docker Compose. The only prerequisites are Docker and Docker Compose.

git clone https://github.com/Blazity/mdcms.git
cd mdcms
cp .env.example .env
docker compose up -d --build

This starts the MDCMS server along with PostgreSQL, Redis, MinIO, and Mailhog. Migrations run automatically on first boot.

Verify the server is running:

curl http://localhost:4000/healthz

Then point your CLI at the server:

npx mdcms init --server-url http://localhost:4000

See the self-hosting guide for environment variable configuration, auth provider setup, and production deployment recommendations.

Features

Feature	Description
Markdown/MDX content	Author content in Markdown or MDX with custom component support
Code-first schema	Define content types, fields, and references in TypeScript with Zod validation
Studio UI	Embeddable React admin interface with a rich document editor, schema browser, and environment management
CLI workflows	Pull content to local files, edit with any tool, push changes back
Client SDK	Type-safe read API for fetching content in your app
Versioning and publishing	Full draft/publish lifecycle with immutable version history
Auth and RBAC	Session auth, OIDC/SAML SSO, API keys, and role-based access control
Environments	Manage multiple environments (production, staging, preview) with schema overlays
i18n	Locale-aware content with translation groups
Extensible modules	First-party module system for extending server and CLI behavior

Packages

Package	npm	Description
@mdcms/cli	npm install @mdcms/cli	CLI for content workflows (pull, push, login, schema sync)
@mdcms/studio	npm install @mdcms/studio	Embeddable Studio UI component for host apps
@mdcms/sdk	npm install @mdcms/sdk	Read-focused client SDK for content APIs
@mdcms/shared	npm install @mdcms/shared	Shared contracts, types, and validators
@mdcms/server	Private	Backend API server (Elysia + PostgreSQL)
@mdcms/modules	Private	First-party module registry

Coming Soon

• Live preview - Real-time content preview in your frontend
• Real-time collaboration - Live co-editing with conflict resolution
• Media management - Upload, organize, and serve media assets via MinIO/S3
• Webhooks - Notify external systems on content lifecycle events
• Full-text search - Search across content with indexing and ranking
• Bulk operations - Batch publish, unpublish, and delete actions

Documentation

Full documentation is available at docs.mdcms.ai.

For architecture decisions and specs, see the docs/ directory.

Development

To work on MDCMS itself, clone the repo and use Bun as the runtime:

git clone https://github.com/Blazity/mdcms.git
cd mdcms
bun install
docker compose up -d --build   # Start Postgres, Redis, MinIO, Mailhog
bun run dev                     # Start backend, Studio watcher, and example app

Visit http://127.0.0.1:4173/admin to open the Studio UI in the example host app.

Default demo credentials:

• Email: demo@mdcms.local
• Password: Demo12345!

See the contributing guide for conventions, branch workflow, and how to run the test suite.

Contributing

We welcome contributions! See the contributing guide for workflow, conventions, and how to get started.

License

MIT