Cms MCP Server

AI-native content engine — open source. Framework-agnostic JSON content with a TypeScript admin.

Render with Next.js · Laravel · Django · Spring Boot · .NET · Rails · Hugo · or anything that reads files.

---

Define your content schema once. Manage it visually. Let AI help write it. Render it from any framework. Deploy anywhere.

Your content lives as flat JSON files in your git repo — readable by Next.js, Laravel, Django, Spring Boot, .NET, Rails, Hugo, or any other language. The CMS admin is a Next.js app, but the content layer is universal. See examples/consumers/ for working Java and .NET reference apps.

npm create @webhouse/cms my-site
cd my-site
bash start.sh

That's it. Claude Code or other AI platforms reads your schema, builds a Next.js site or through other frameworks, and you manage content through the admin UI.

More screenshots

---

What is this?

@webhouse/cms is a file-based, code-first content management system. You define collections and fields in cms.config.ts, and the CMS stores content as flat JSON files in a content/ directory. No database required. Git-committable. AI-native from day one.

// cms.config.ts
import { defineConfig, defineCollection } from '@webhouse/cms';

export default defineConfig({
  collections: [
    defineCollection({
      name: 'posts',
      label: 'Blog Posts',
      fields: [
        { name: 'title', type: 'text', required: true },
        { name: 'excerpt', type: 'textarea' },
        { name: 'content', type: 'richtext' },
        { name: 'date', type: 'date' },
        { name: 'author', type: 'relation', collection: 'team' },
        { name: 'tags', type: 'tags' },
        { name: 'featured', type: 'boolean' },
      ],
    }),
  ],
});

Content is stored as JSON — read it directly in Next.js, Astro, or any framework:

// Read content — no SDK, no API, just files
import { readFileSync } from 'node:fs';
const post = JSON.parse(readFileSync('content/posts/hello-world.json', 'utf-8'));
console.log(post.data.title); // "Hello, World!"

---

Admin UI — 5 ways to run it

The visual admin interface for managing content. Open source, full-featured, works with any site.

1. Hosted cloud (coming soon)

https://webhouse.app

Sign in, connect your GitHub repo, manage content from anywhere. Zero setup.

2. npx — one command, local install

npx @webhouse/cms-admin-cli

Auto-detects cms.config.ts in your project. First run builds and caches the admin (~2 min). Subsequent starts are instant.

npx @webhouse/cms-admin-cli --config ./cms.config.ts  # explicit config
npx @webhouse/cms-admin-cli -p 4000                    # custom port
npx @webhouse/cms-admin-cli --update                   # force rebuild

3. Docker — isolated, reproducible

docker run -p 3010:3010 -v $(pwd):/site ghcr.io/webhousecode/cms-admin:latest

Published to GHCR for linux/amd64 + linux/arm64. Mounts your project at /site, auto-detects cms.config.ts, serves admin on port 3010.

• Stable: :latest or :0.3.0 — tagged releases
• Weekly: :weekly — automated Monday builds

4. Tarball — Node.js only, no Docker

curl -L https://github.com/webhousecode/cms/releases/latest/download/cms-admin.tar.gz | tar xz
cd cms-admin-*
./run.sh

Requires Node.js 22+. Runs on Linux, macOS, and Windows (WSL/Git Bash). First boot prompts for admin email + password via the setup wizard. See docs.webhouse.app/docs/releases for all download channels, or the plain-text releases.txt feed for scripts.

5. Git clone — full source access

git clone https://github.com/webhousecode/cms.git
cd cms
pnpm install
pnpm dev

Admin runs on localhost:3010. Set CMS_CONFIG_PATH to point at your site's config.

---

Features

Content engine

• 16 field types — text, textarea, richtext, number, boolean, date, image, video, select, tags, relation, array, object, blocks, image-gallery
• Block editor — composable page sections with nested fields
• Relations — cross-collection references (single and multi)
• Structured arrays — arrays of objects with per-item field editors
• Nested objects — deeply nested field structures with JSON/UI toggle
• i18n — multi-locale content with AI-powered translation
• Scheduled publishing — set a future date, auto-publishes

Admin UI

• Visual document editor — every field type has a dedicated editor
• Block editor — drag-and-drop sections with type picker
• Multi-site management — manage multiple sites from one admin
• GitHub integration — OAuth login, create repos, manage GitHub-backed content
• Site switcher — fast switching between projects
• Rich text editor — Markdown with live preview
• Media library — upload, browse, and manage images
• Revision history — view diffs and restore previous versions
• AI assistant — generate, rewrite, and optimize content from the editor

AI-native

• Content generation — cms ai generate posts "Write about TypeScript generics"
• Rewriting — cms ai rewrite posts/hello "Make it more concise"
• SEO optimization — cms ai seo across all published content
• AI Lock — field-level protection prevents AI from overwriting human edits
• Brand voice — configurable tone, audience, and style guidelines
• MCP support — expose content to AI assistants via Model Context Protocol

Developer experience

• TypeScript-first — schemas defined in code, fully typed
• File-based — JSON files in content/, git-committable
• No database — filesystem adapter by default, SQLite and GitHub also available
• CLI tools — init, dev, build, serve, AI commands
• Claude Code ready — CLAUDE.md included in npm package, .mcp.json pre-configured

---

Storage adapters

Adapter	Description	Best for
Filesystem (default)	JSON files in content/	Local dev, git workflows
GitHub	Read/write via GitHub API	Headless sites, multi-editor
SQLite	Local database via Drizzle ORM	API-heavy use cases

// Filesystem (default)
storage: { adapter: 'filesystem', filesystem: { contentDir: 'content' } }

// GitHub
storage: { adapter: 'github', github: { owner: 'myorg', repo: 'my-site', token: process.env.GITHUB_TOKEN } }

// SQLite
storage: { adapter: 'sqlite', sqlite: { path: './data/cms.db' } }

---

Packages

Package	Description	npm
@webhouse/cms	Core engine — schema, storage, content service
@webhouse/cms-cli	CLI — init, dev, build, AI commands, MCP server
@webhouse/cms-ai	AI agents — generate, rewrite, translate, SEO
@webhouse/cms-admin-cli	Run admin UI locally via npx
@webhouse/cms-mcp-client	Public read-only MCP server
@webhouse/cms-mcp-server	Authenticated MCP server (full CRUD)
@webhouse/create-cms	Project scaffolder — npm create @webhouse/cms

---

CLI

Install globally for the short cms command:

npm install -g @webhouse/cms-cli

Note: Do not use npx cms — npm resolves it to an unrelated package. Use npx @webhouse/cms-cli if you prefer not to install globally.

Commands

Command	Description
cms init [name]	Scaffold a new project
cms dev [--port 3000]	Start dev server with REST API and hot reload
cms build [--outDir dist]	Build static site (HTML, sitemap, llms.txt)
cms serve [--port 5000]	Serve built site locally

AI commands

Require ANTHROPIC_API_KEY or OPENAI_API_KEY in .env.

Command	Description
cms ai generate <collection> "<prompt>"	Generate a new document with AI
cms ai rewrite <collection>/<slug> "<instruction>"	Rewrite existing content
cms ai seo [--status published]	Run SEO optimization across all documents

# Examples
cms ai generate posts "Write a guide to TypeScript generics"
cms ai rewrite posts/hello-world "Make it more concise and add code examples"
cms ai seo

MCP commands

Command	Description
cms mcp serve	Start stdio MCP server (for Claude Code / .mcp.json)
cms mcp keygen	Generate MCP API key
cms mcp test	Test MCP server connection
cms mcp status	Check MCP server status

Content creation — 3 ways

A) Via AI generation

cms ai generate posts "Write a blog post about TypeScript best practices"

B) Via REST API

curl -X POST http://localhost:3000/api/content/posts \
  -H "Content-Type: application/json" \
  -d '{"slug":"my-post","status":"published","data":{"title":"My Post","content":"# Hello"}}'

C) Via Claude Code

> Create a blog post about why file-based CMS is the future

---

REST API

The dev server (cms dev) exposes a full REST API. See the complete OpenAPI specification.

Endpoints

Method	Endpoint	Description
GET	/api/manifest	CMS configuration and collection list
GET	/api/schema/:collection	JSON Schema for a collection
GET	/api/content/:collection	List all documents in a collection
GET	/api/content/:collection/:slug	Get a single document by slug
POST	/api/content/:collection	Create a new document
PATCH	/api/content/:collection/:slug	Update a document
DELETE	/api/content/:collection/:slug	Delete a document
GET	/api/content/:collection/:slug/_fieldMeta	Get field-level AI lock metadata
PATCH	/api/content/:collection/:slug/_fieldMeta	Update field locks

Example

# List all published posts
curl http://localhost:3000/api/content/posts?status=published

# Get a single post
curl http://localhost:3000/api/content/posts/hello-world

# Create a post
curl -X POST http://localhost:3000/api/content/posts \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "my-post",
    "status": "draft",
    "data": {
      "title": "My First Post",
      "content": "# Hello\n\nThis is my first post.",
      "date": "2026-03-15"
    }
  }'

---

Building a site with Claude Code

Every scaffolded project includes a CLAUDE.md that teaches AI how to use the CMS. The @webhouse/cms npm package also ships with a comprehensive CLAUDE.md.

# Scaffold and let AI build your site
npm create @webhouse/cms my-site
cd my-site
claude "Build a portfolio site with Next.js and Tailwind. Read CLAUDE.md for CMS docs."

Or use the included start script:

bash start.sh "Build a dark-themed blog with categories and author pages"

Claude Code will:

1. Read CLAUDE.md and understand the CMS
2. Create a Next.js App Router site
3. Define collections in cms.config.ts
4. Create content in content/ as JSON files
5. Build pages that read content from the filesystem
6. Suggest running the admin UI when done

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│  webhouse.app / cms-admin              (Visual Admin UI)    │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐   │
│  │ Document │ │  Block   │ │  Media   │ │  AI Cockpit  │   │
│  │  Editor  │ │  Editor  │ │ Library  │ │  & Agents    │   │
│  └──────────┘ └──────────┘ └──────────┘ └──────────────┘   │
├─────────────────────────────────────────────────────────────┤
│  @webhouse/cms                          (Core Engine)       │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐   │
│  │  Schema  │ │ Content  │ │ Storage  │ │     API      │   │
│  │ Validate │ │ Service  │ │ Adapters │ │   (Hono)     │   │
│  └──────────┘ └──────────┘ └──────────┘ └──────────────┘   │
├─────────────────────────────────────────────────────────────┤
│  Storage                                                    │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐                    │
│  │Filesystem│ │  GitHub  │ │  SQLite  │                    │
│  │  (JSON)  │ │   API    │ │ (Drizzle)│                    │
│  └──────────┘ └──────────┘ └──────────┘                    │
├─────────────────────────────────────────────────────────────┤
│  AI Layer                                                   │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐   │
│  │ Generate │ │ Rewrite  │ │Translate │ │  SEO Agent   │   │
│  └──────────┘ └──────────┘ └──────────┘ └──────────────┘   │
│  ┌──────────┐ ┌──────────┐                                  │
│  │ MCP Read │ │MCP Write │  (Model Context Protocol)       │
│  └──────────┘ └──────────┘                                  │
└─────────────────────────────────────────────────────────────┘

---

Development

git clone https://github.com/webhousecode/cms.git
cd cms
pnpm install
pnpm build          # Build all packages
pnpm dev            # Start admin on :3010

Project structure

packages/
  cms/              # Core engine
  cms-admin/        # Next.js admin UI
  cms-admin-cli/    # npx wrapper for admin
  cms-ai/           # AI agents
  cms-cli/          # CLI tools
  cms-mcp-client/   # Public MCP server
  cms-mcp-server/   # Admin MCP server
  create-cms/       # Project scaffolder
examples/
  blog/             # Blog example
  landing/          # Landing page with blocks
deploy/
  Dockerfile.cms    # Combined site + admin image
  Dockerfile.admin  # Standalone admin image
  fly.toml          # Fly.io deployment config

---

License

MIT — WebHouse

_{Built with conviction by WebHouse — 30 years of building for the web.}