pencms MCP server
Commit Oct 17, 2026Allows AI agents and humans to collaborate on Markdown-centric content through a headless CMS with a native MCP server.
Also known as slpstream/pencms
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 17, 2026
- License
- MIT
What is pencms MCP?
pencms allows AI agents and humans to collaborate on Markdown-centric content through a headless CMS with a native MCP server.
Summary generated from the project's README
About pencms MCP server
Collaborating on Markdown-centric content with both AI agents and humans is what pencms enables through its headless architecture. This self-hosted system uses a Python FastAPI backend and a PHP admin frontend to manage flat files. Because it relies on Markdown and YAML rather than a secondary database for drafts, agents and people always work on the same source of truth.
Developers can deploy this locally on a laptop or on a VPS using Docker Compose and Caddy. The setup requires a Python backend running on port 8008 and a PHP frontend on port 8009. Agents interact with the system via the MCP endpoint at /api/mcp using revocable access keys. This allows for high-speed reading and writing while maintaining control over Git remotes, disk storage, and TLS settings. The system also includes a local SQLite index to ensure queries remain responsive even on smaller machines.
What you can do with it
- 1Agentic content creationAn AI agent can read and write directly to your Markdown files to publish new posts.
- 2Synchronizing with remote repositoriesYou can sync your content to GitHub or GitLab using HTTPS REST APIs without needing shell access.
- 3Managing multi-agent workflowsA single operator can manage multiple AI agents by issuing individual access keys.
- 4Human-led content administrationUsers can manage themes, storage, and structure through a dedicated PHP admin interface.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
PHP_CLI_SERVER_WORKERS
| Name | Description | |
|---|---|---|
| PHP_CLI_SERVER_WORKERS | — |
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableslpstream/pencms is public and reachablegithub.com/slpstream/pencms ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-17github.com/slpstream/pencms ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubMany agents via keys. One operator.
PenCMS is a self-hosted, MIT-licensed Markdown and Git CMS with a Python (FastAPI) backend and a PHP admin frontend. Humans and agents edit the same flat files with no hidden state or secondary database. You control the machine — disk, Git remotes, TLS, and revocable access keys — while agents read and publish directly through MCP.
Self-Hosting PenCMS? Follow the step-by-step Quickstart Guide to get the Python Backend and PHP Frontend running on your machine in 5 minutes.
Key Principles
- Contract-First: Every backend endpoint, schema, and validation rule is defined in a hand-written OpenAPI specification (
core/openapi.yaml). - Flat-File Source of Truth: All pages, posts, and entries are stored as clean Markdown + YAML files. No second database of “AI drafts.”
- Two doors: PHP admin for humans (structure, keys, themes, storage); MCP (
/api/mcp) for agents (read/write at agent speed). - High-Performance Query Cache: Reads use a local SQLite index on write, so the CMS stays responsive on small machines.
- Shell-Free Git Syncing: Remote repos (GitHub/GitLab) via HTTPS REST APIs when a shell is restricted.
- Selfhosting: Run locally, on LAN HTTPS, or a small VPS.
PenCMS v0.2.0 explicitly bundles Traven Editor v0.3.0.
Repository Structure
pencms/
├── core/ # Contract & Specifications
│ ├── openapi.yaml # API Spec (Source of Truth)
│ ├── schemas/ # Document Schemas
│ └── docs/ # Guides (incl. quickstart.md, mcp_guide.md)
│
├── backend-python/ # FastAPI CMS + MCP + OAuth (the product brain, its backend)
│
└── frontend-php/ # Admin UI client (bundles Traven Editor v0.3.0)
Run / Deploy
| Path | Doc |
|---|---|
| Self-hosting on your own hardware (ELI5 Quickstart) | Step-by-step beginner guide — core/docs/quickstart.md |
| VPS / public HTTPS | Docker Compose + Caddy — core/docs/deploy_compose.md (deploy/) |
| LAN home server | mkcert + reverse proxy — core/docs/lan_https.md |
| An agent’s own site | core/docs/agent-owned-site.md |
| Agents / MCP / OAuth | core/docs/mcp_guide.md |
| Users + agent keys | core/docs/users-and-access.md |
2-Minute Local Quickstart (Laptop / Desktop)
PenCMS runs as two coordinated engines—the Python Backend (API & storage on :8008) and the PHP Frontend (Admin UI & Blog on :8009).
-
Start the Backend (Terminal 1):
cd backend-python python3 -m venv venv && source venv/bin/activate pip install -r requirements.txt playwright install chromium uvicorn app.main:app --reload --port 8008 -
Start the Frontend (Terminal 2):
cd frontend-php PHP_CLI_SERVER_WORKERS=8 php -c php.ini -S 127.0.0.1:8009 -t public router.php -
Initialize & Explore:
- Create your admin account: http://127.0.0.1:8009/admin/setup.php
- Admin Dashboard: http://127.0.0.1:8009/admin/
- Public Blog: http://127.0.0.1:8009/blog/
👉 For full step-by-step guidance, home server setup, and troubleshooting, read the ELI5 Quickstart Guide.
Docker Compose (VPS / Public HTTPS)
For cloud VPS deployments with automatic Let's Encrypt TLS:
cd deploy
cp .env.example .env # set PUBLIC_HOST, JWT_SECRET, JWT_ISSUER, MCP_RESOURCE_URL, CORS_ALLOW_ORIGINS
docker compose up -d --build
See core/docs/deploy_compose.md for full VPS configuration and reverse proxy details.
License
Open-source, licensed under the MIT License.
pencms MCP questions
How do humans and AI agents interact with the content?
Humans use the PHP admin frontend while agents use the MCP server to read and write content directly.
Where is the content stored?
All pages, posts, and entries are stored as clean Markdown and YAML files in a flat-file system.
Does it require a database?
It uses a flat-file source of truth, though it utilizes a local SQLite index on write to maintain high-performance queries.