
Self-hosted, open-source headless CMS in TypeScript on PostgreSQL β React admin with visual on-page
Self-hosted, open-source headless CMS in TypeScript on PostgreSQL β React admin with visual on-page editing, typed Delivery API, and an MCP server for AI agents. DPX: Don't Pay eXtra. π°
Β·
The MCP-first headless CMS. Point Claude, Cursor or any MCP client at Paperboy and it can build pages, translate them, fix SEO, migrate redirects and publish on a schedule β as a real user, with that user's permissions, through the same validation and audit trail as your editors. Then open the admin: a visual editor where you click any text on your live site and change it.
Agents do the volume. People decide what goes live. Self-hosted, MIT, one container and a Postgres.
Paperboy ONE β Open, No Extras. Β· DPX β Don't Pay eXtra. A proper headless CMS without the "experience platform" invoice.
The website you build on is a separate repo, the Astro starter.
| Your agent (MCP) | Your editors (admin) | |
|---|---|---|
| Gets in with | OAuth sign-in with a Paperboy login (2FA included) or a site-scoped token | Password, or email + TOTP code once 2FA is on |
| Sees | Only the tools its role can use β an Author is never offered publish, users or webhooks | Only the sections and actions its role allows |
| Writes through | The same Zod validation, RBAC and audit log β parity is test-enforced | β same |
| Is recorded as | via: mcp on every version, badged Agent edited | via: web |
https://<your-domain>/mcp as a connector.Running locally? An admin mints a token in Settings β Agent access and use stdio β see MCP setup.
Every rule below exists because a real agent run broke without it.
set_field takes one flat string, because some clients mangle long
strings nested in JSON.create_upload_link gives the agent a 15-minute upload URL;
no base64 through the context window.CLAUDE.md.Where to start****Where to start
| You want to⦠| Go to |
|---|---|
| Connect an AI agent | Connect your agent Β· MCP setup |
| Try it in five minutes | Quickstart Β· Windows, no experience needed |
| Build a website on it | Astro starter, or any framework with @paperboycms/client and @paperboycms/preview |
| Run it for real | Production Β· Backups |
| Work on the CMS itself | Developing Β· CONTRIBUTING.md Β· CLAUDE.md |
Click any text on your page and edit it right there. The preview is your real frontend, not a mock-up, and it updates as you type.
Your site stays yours. This is the Astro starter's demo site, every page of it built through the Management API. One command runs it with the CMS: docker compose -f docker-compose.demo.yml up -d --build.
Built for agents
@paperboycms/client, typed from the same Zod schemas the server serializes with. No codegen.Content
Delivery
fieldTypes so frontends switch on schema.dateModified) on every page. Preview is always noindex.matchRedirect; a 404 log shows what visitors miss.?w=800&format=webp&q=75 on any media URL, generated once and cached.content.published, form.submitted and delivery.changed for every move, sort or settings change, so a cache can purge on webhooks alone.Editing
@paperboycms/preview.What ships in the box as of 2026-10-17. core = built in Β· plugin Β· paid Β· no. Every cell is sourced in docs/comparison-sources.md; corrections welcome.
| Paperboy | Strapi | Payload | Directus | Sanity | |
|---|---|---|---|---|---|
| License | MIT | MIT + paid tiers | MIT | source-available | closed backend |
| Self-host | one image | Node app | your Next.js app | one image | no |
| Forms, validated server-side | core | plugin | plugin, partial | no | no |
| SEO meta + JSON-LD from the CMS | core | plugin, no JSON-LD | plugin, no JSON-LD | plugin, no JSON-LD | no |
| Auto 301 on rename | core | plugin | plugin, manual | no | DIY |
| MCP server acting as a user | core | core | plugin (beta) | core | core |
| Multisite | core | no | plugin | pattern | datasets |
| Click-to-edit on the live page | core | paid | soon | core | core |
| GraphQL | no | plugin | core | core | core |
| Hosted option | no | paid | paused | paid | yes |
| Ecosystem | none yet | large | growing | growing | large |
1. Run the CMS (Docker):
./scripts/setup.sh # writes .env with unique secrets and your admin password β required
docker compose up -d # db β init (migrate + seed) β api, which also serves the admin
# Admin http://localhost:8090 API http://localhost:8091 (OpenAPI UI at /api/docs)setup.sh is safe to re-run and never overwrites .env. Paperboy refuses to boot on the
placeholder secrets in this repo and refuses to seed production with the published demo login.
2. Run the website. The Astro starter renders every built-in content type and is where your site lives:
git clone https://github.com/hybriden/paperboy-astro-starter my-site
cd my-site && npm install && npm run setup && npm run dev # http://localhost:4321The admin's side-by-side preview points at http://localhost:4321 by default. apps/web in this
repo is a Next.js contract reference, not a site to build on; it is opt-in
(docker compose --profile web up -d web, :8092).
powershell in the address bar, press Enter.powershell -ExecutionPolicy Bypass -File .\scripts\setup.ps1docker compose up -d (the first run downloads for a few minutes).Everyday: docker compose stop / docker compose start / docker compose ps.
β οΈ Never run
docker compose down -vonce you have content:-vdeletes the database. If a page won't load, check that Docker Desktop says Engine running.
The generated .env targets localhost. Before exposing a real host set COOKIE_SECURE=true, drop
ALLOW_INSECURE_COOKIES, and point CORS_ORIGIN at the admin's HTTPS origin. Redeploy one service
with docker compose up -d --no-deps --force-recreate <svc>; the seed refuses to wipe a database that
holds content unless FORCE_SEED=1. The deploy-safety rules are in CLAUDE.md.
Without a VM. One container, no proxy: it fits any "run a container" platform (App Service, Container Apps, Cloud Run, Fly, Render, Railway) plus a managed Postgres.
| Setting | Value |
|---|---|
| Image | ghcr.io/hybriden/paperboy-app:latest |
| Port | the platform's PORT (or API_PORT) |
DATABASE_URL | postgresql://β¦@host:5432/paperboy?sslmode=require |
| Secrets | SESSION_SECRET, CSRF_SECRET, MFA_SECRET via openssl rand -hex 32; PREVIEW_SECRET too, set to the same value on your frontend, for draft preview |
CORS_ORIGIN | the admin's HTTPS origin, with COOKIE_SECURE=true |
TRUST_PROXY | the load-balancer range, so rate limits see real IPs; include your frontend's address if it forwards visitors' (submitForm({ visitorIp })) |
DELIVERY_RATE_MAX | delivery reads per route per minute from one address (default 6000); your frontend's server is one address |
| Storage | a persistent volume at /app/uploads |
| Remote MCP | MCP_EMBEDDED=true serves the MCP inside the same container at {PUBLIC_URL}/mcp |
Run one replica: rate limits and the publish/retention timers are in-process. Migrations run on
boot. Create the first admin by running the image once with pnpm --filter @paperboy/db seed and real
SEED_ADMIN_EMAIL, SEED_ADMIN_PASSWORD, PAPERBOY_PUBLIC_KEY, PAPERBOY_PREVIEW_KEY.
Without a Postgres server. For a demo or a small site, DATABASE_URL=pglite:///data/db runs
Postgres inside the container (PGlite, the same schema and migrations) with the
database in a folder. Seeded on first boot, never reseeded:
docker run -d -p 8090:8091 -v paperboy:/data \
-e DATABASE_URL=pglite:///data/db -e UPLOADS_DIR=/data/uploads \
-e SESSION_SECRET=$(openssl rand -hex 32) -e CSRF_SECRET=$(openssl rand -hex 32) \
-e COOKIE_SECURE=false -e ALLOW_INSECURE_COOKIES=true -e ALLOW_DEMO_CREDENTIALS=true \
ghcr.io/hybriden/paperboy-app # http://localhost:8090, [email protected] / Admin!Passw0rdThat is a localhost demo. Exposed, use HTTPS settings and real seed values as below. It is one
Postgres session, so writes queue: fine for a small site, not for heavy traffic. Expect ~0.5 GB of
memory. Back it up with ops/backup-pglite.sh, which stops the container for a few seconds, archives the volume and starts it again.
Accounts. Your admin login is what setup.sh printed. The demo logins (editor@, author@,
viewer@, passwords <Role>!Passw0rd) are development fixtures: a production seed creates only the
admin unless ALLOW_DEMO_CREDENTIALS=true.
Nothing backs itself up. ops/backup.sh is a working reference: nightly pg_dump
plus a tar of the uploads volume, 14-day rotation, alert on failure. It refuses to succeed with an
empty media archive and writes mode-600 files, because a backup is a full credential dump and,
once you have forms, visitor personal data. Cron lines and the restore procedure are in
ops/README.md. Known gap: backups land on the same disk as the data; add one
rclone copy line once you have a bucket.
Remote clients (Streamable HTTP). Start the MCP container; the api forwards /mcp to it, so
clients use the admin's own domain:
docker compose --profile mcp up -d --no-deps mcp # β https://<your-domain>/mcpOn a one-container host, set MCP_EMBEDDED=true on the api instead and it serves the MCP itself.
Local clients (stdio). The client starts the server, so this goes in its config, not a terminal.
An admin mints a token in Settings β Agent access and point -C at your Paperboy checkout (after pnpm install):
{
"mcpServers": {
"paperboy": {
"command": "pnpm",
"args": ["-s", "-C", "/path/to/paperboy", "--filter", "@paperboy/mcp", "start"],
"env": {
"MCP_TOKEN": "mcp_β¦",
"DATABASE_URL": "postgresql://paperboy:paperboy@localhost:5433/paperboy"
}
}
}
}Keep -s: without it pnpm prints its script banner to stdout, which corrupts the stdio protocol.
The MCP acts as a Paperboy user and inherits its permissions. Tokens are minted per site (or for
every site); PAPERBOY_SITE pins a server to one site, and every per-site tool also takes a per-call site.
Toolsets. A connection lists the content tools by default (writing, editing, publishing,
media). The rest is opt-in, so an agent writing a page isn't choosing among user and webhook tools:
| Toolset | For |
|---|---|
content (default) | pages, blocks, globals, versions, trash, media, the writing assistant |
delivery | what the public website receives (published output, search) |
schema | content types and type templates |
redirects | redirect rules and the 404 log |
experiments | A/B tests of a page's content area: set up, start, pause, read results, end |
forms | form submissions (export, erasure) |
admin | users, delivery keys, webhooks, audit log, start page |
Pick them with PAPERBOY_TOOLSETS=content,redirects on the server (in .env with Docker Compose), or per connection on the URL:
https://<your-domain>/mcp?toolsets=content,redirects (all lists everything). Your role still
decides what you may do; a tool outside the chosen toolsets answers with how to enable it.
OAuth for remote clients. Add https://<your-domain>/mcp as a connector in Claude or Cursor. The
client registers itself, sends you through Paperboy's own login (with 2FA), and a consent screen asks
which site the connection may work in. Revoke it in Settings β Connected apps. One domain is enough:
the API forwards /mcp and serves /.well-known/oauth-*. For other layouts set PUBLIC_URL (the
issuer, default CORS_ORIGIN) and MCP_PUBLIC_URL (default {PUBLIC_URL}/mcp) on both api and mcp.
Files from the agent's machine. create_upload_link mints a 15-minute link the agent curls files
to (POST /api/v1/uploads, 20 files of 5 MB per request). upload_asset takes a public URL or base64.
Frontends integrate against these two packages, not the CMS codebase. Both are versioned independently.
@paperboycms/client β dependency-free, typed end to end:
import { createClient, mediaUrl } from "@paperboycms/client";
const cms = createClient({ baseUrl: "https://cms.example.com", key: process.env.PAPERBOY_PUBLIC_KEY! });
const post = await cms.getBySlug<BlogPost>("hello-world", { locale: "en" });
const { items } = await cms.list<BlogPost>("BlogPost", { sort: "-data.publishDate", limit: 10 });
const src = post?.data.image && mediaUrl(post.data.image.url, { w: 640, format: "webp" }); // image fields arrive as {url, alt, β¦}Also getByPath, startPage, global, search, render helpers that follow fieldTypes,
matchRedirect, applyExperiments for A/B tests, formToolAttrs for WebMCP forms,
preview-token verification and an optional ETag cache. 404s return null, other
errors throw PaperboyError. Full README.
@paperboycms/preview β zero-dependency bridge that makes any frontend
editable inside the admin's preview. Call initPreviewBridge() in preview mode and mark the DOM with
data-pb-field, data-pb-area and data-pb-block-index (or let the client's pbAreaAttrs emit
them). Full README.
apps/api Fastify v5 β Management API (auth/RBAC) + Delivery API (read-only, key-scoped); serves the admin
apps/admin React 19 + Vite β the editor
apps/web Next.js 15 β reference frontend, pins the delivery contract (opt-in)
apps/mcp MCP server (stdio or Streamable HTTP)
packages/shared Zod schemas + types (single source of truth) + the AI provider
packages/db Drizzle schema, migrations, query layer (object-level authz), seed
packages/client @paperboycms/client β typed Delivery API SDK (npm)
packages/preview @paperboycms/preview β on-page-editing bridge (npm)pnpm install
docker compose up -d db
export DATABASE_URL=postgresql://paperboy:paperboy@localhost:5433/paperboy
export UPLOADS_DIR=$PWD/.uploads # the default, /app/uploads, is the container path
pnpm db:seed
pnpm dev # api :8091, admin :8090, web :8092 (mcp waits for MCP_TOKEN)
pnpm --filter @paperboy/api test # integration tests against a real Postgres
pnpm --filter @paperboy/admin test:e2e # Playwright e2e + axeCI also runs the MCP usability eval (evals/) on every push with a deterministic mock driver and
weekly with a real model. Rules of the road: CONTRIBUTING.md. Everything about
deploy safety, auth, the content model and the incidents behind each rule: CLAUDE.md.
Stack choices: STACK.md. Research behind the bigger features: docs/plans/.
Vulnerabilities: SECURITY.md.
MIT β Don't Pay eXtra. π°
Pick your client and paste the snippet. Each one is the same server, written the way that client expects it.
claude mcp add paperboy -- pnpm -s -C /path/to/paperboy --filter @paperboy/mcp start{
"mcpServers": {
"paperboy": {
"env": {
"MCP_TOKEN": "",
"DATABASE_URL": ""
},
"args": [
"-s",
"-C",
"/path/to/paperboy",
"--filter",
"@paperboy/mcp",
"start"
],
"command": "pnpm"
}
}
}code --add-mcp '{"name":"paperboy","env":{"MCP_TOKEN":"","DATABASE_URL":""},"args":["-s","-C","/path/to/paperboy","--filter","@paperboy/mcp","start"],"command":"pnpm"}'[mcp_servers.paperboy]
command = "pnpm"
args = ["-s", "-C", "/path/to/paperboy", "--filter", "@paperboy/mcp", "start"]Runs locally on your device. Your client starts the server itself, so nothing has to be hosted.
Paste this prompt into your agent. It reads this page and does the setup for you.
Read https://aiagentslisting.com/mcp/paperboy to learn what the "Paperboy" MCP server does and how to install it. Add it to my coding agent's MCP configuration as documented on that page, then confirm the server connects and list the tools it exposes.Agents can also browse this directory over MCP at https://aiagentslisting.com/api/mcp
docker run -d -p 8090:8091 -v paperboy:/dataThis server runs locally, so we can't read its tool list over the web yet.
We could not run this server: it ships no npx package for our sandbox and no public endpoint. The four checks that need a live server are left out, and the grade tops out at B until one exists.
Maintain this server? Claiming proves you own the listing and earns the last 4 points.
Claim this listingPaste this line near the top of your repository's README. The badge always renders the current score.
[](https://aiagentslisting.com/mcp/paperboy)Nothing comparable is listed yet.
v0.3.0v0.3.0 β one container, forms, redirects, structured data, remote MCPRelease notesConnect to the AI Agents Listing MCP server at https://aiagentslisting.com/api/mcp using the HTTP transport and complete the sign-in when it asks. Then call the submit_review tool for the listing "paperboy" with a rating from 1 to 5 and a short note on what worked and what did not.No reviews yet
Be the first to share your experience with this tool.
One email a week. New agents, MCP servers and skills, and what is actually getting traction.