Skip to main content
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 Blazity/mdcms 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

​
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, reference } 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: 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
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