Quick Start - MDCMS

Get MDCMS running in your own application. This guide assumes you have an MDCMS server available (self-hosted or managed).

Need to set up your own server first? Follow the Self-Hosting guide to get MDCMS running with Docker Compose, then come back here.

Looking to contribute to MDCMS itself? See Development Setup.

Using an AI coding agent? npx skills add mdcms-ai/mdcms/skills installs the MDCMS Skills Pack so your agent can walk through this quickstart for you.

1. Install the CLI

npm install --save-dev @mdcms/cli

bun add -D @mdcms/cli

2. Initialize your project

The mdcms init wizard configures everything — server connection, project/environment selection, content type detection, and initial sync:

npx mdcms init

It will:

Ask for your MDCMS server URL
Open a browser for authentication
Scan your repo for existing Markdown/MDX files
Generate a mdcms.config.ts with inferred content types
Push the initial schema and content to the server

See CLI Installation for details on the init wizard.

3. Define your content schema

The generated mdcms.config.ts is your starting point. Customize it to match your content model:

mdcms.config.ts

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

const Author = defineType("Author", {
  directory: "content/authors",
  fields: {
    name: z.string().min(1),
    bio: z.string().optional(),
  },
});

const BlogPost = defineType("BlogPost", {
  directory: "content/blog",
  localized: true,
  fields: {
    title: z.string().min(1),
    author: fieldTypes.reference("Author"),
    tags: z.array(z.string()),
  },
});

export default defineConfig({
  project: "my-site",
  environment: "production",
  serverUrl: "https://your-mdcms-server.example.com",
  contentDirectories: ["content"],
  locales: {
    default: "en",
    supported: ["en", "fr"],
  },
  types: [Author, BlogPost],
});

See the Schema Guide for field types, references, and environment overlays.

4. Sync schema and content

# Push your schema to the server
npx mdcms push

# Pull content from the server to local Markdown files
npx mdcms pull

# Edit .md or .mdx files with any tool, then push changes back
npx mdcms push

See the CLI Commands reference for all available flags.

5. Fetch content in your app

Install the SDK:

npm install @mdcms/sdk

bun add @mdcms/sdk

Query content in your application:

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",
});

// List published blog posts
const { data: posts } = await cms.list("BlogPost", {
  locale: "en",
  published: true,
  limit: 10,
});

// Fetch a single post with resolved references
const post = await cms.get("BlogPost", {
  slug: "hello-world",
  resolve: ["author"],
});

See the SDK reference for the full API.

6. Embed the Studio UI (optional)

Add a visual editing interface to your app by installing @mdcms/studio and mounting it on a catch-all route:

app/admin/[[...path]]/page.tsx

import { createStudioEmbedConfig } from "@mdcms/studio/runtime";
import config from "../../../mdcms.config";
import { AdminStudioClient } from "./admin-studio-client";

export default async function AdminPage() {
  return <AdminStudioClient config={createStudioEmbedConfig(config)} />;
}

For the full setup — including MDX component registration, authentication, CORS configuration, and production hardening — see the Integration Guide.

Next steps

CLI Commands

Push, pull, login, schema sync, and all CLI flags

Schema Guide

Field types, references, environment overlays, MDX components

Studio Guide

Visual content editing, publishing, and version history

SDK Reference

Full typed client API for content reads

​1. Install the CLI

​2. Initialize your project

​3. Define your content schema

​4. Sync schema and content

​5. Fetch content in your app

​6. Embed the Studio UI (optional)

​Next steps

CLI Commands

Schema Guide

Studio Guide

SDK Reference

1. Install the CLI

2. Initialize your project

3. Define your content schema

4. Sync schema and content

5. Fetch content in your app

6. Embed the Studio UI (optional)

Next steps