Cms MCP Server

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.

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

// 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

AI commands

Require ANTHROPIC_API_KEY or OPENAI_API_KEY in .env.

# 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

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

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