The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Velocms MCP listing page.
An MCP server for VeloCMS — draft, edit, publish, and manage your blog (posts, media, comments, members, site settings) from Claude Code, Claude Desktop, Cursor, or any other MCP client.
It's a thin, typed wrapper around the VeloCMS Public API
(https://<your-blog>/api/v1, documented at
/api/openapi on any VeloCMS site): every
tool maps to one real API call, with Zod-validated inputs and readable
errors — no scraping, no browser automation, just the platform's own
supported REST API.
| Tool | What it does |
|---|---|
list_posts | List posts, paginated, optionally filtered by status (draft/published) |
get_post | Fetch a single post by ID, including its full content and SEO fields |
create_post | Create a new post (defaults to draft) |
update_post | Partially update an existing post — only the fields you pass change |
delete_post | Permanently delete a post |
publish_post | Set a post's status to published (stamps published_at) |
unpublish_post | Set a post's status back to draft |
list_media | List the media library, paginated, optionally filtered by MIME type |
list_comments | List comments, paginated, optionally filtered by post or moderation status |
moderate_comment | Set a comment's status to approved, pending, or spam |
list_members | List subscribers/readers (emails are masked, e.g. u***@example.com) |
get_site_settings | Read the blog's name, description, and feature flags |
Every tool ships a description an LLM can read to figure out when and how to use it — that's the point of MCP, not just a REST proxy with extra steps. See Tool reference below for full argument lists.
In your VeloCMS dashboard: Settings → API Keys → create a key with the
scopes you need (posts:read, posts:write, media:read, comments:read,
comments:moderate, members:read, site-settings:read, etc.). API access
requires the Pro plan or higher.
You don't need to clone this repo — npx fetches and runs it on demand.
MCP servers register their tools at session start, so restart your Claude Code session after adding this.
Add to your claude_desktop_config.json (Settings → Developer → Edit
Config):
Restart Claude Desktop after editing.
Same shape as above — point the client's MCP config at
npx -y -p @velocms/mcp velocms-mcp with VELOCMS_SITE_URL and
VELOCMS_API_KEY set in its env. The server speaks standard MCP over
stdio, so any client that supports stdio MCP servers works.
| Env var | Required | Description |
|---|---|---|
VELOCMS_SITE_URL | yes | Your blog's base URL — a *.velocms.org subdomain or a bound custom domain. No trailing slash needed. |
VELOCMS_API_KEY | yes | An API key from /admin/settings → API Keys. Requires Pro plan or higher. Never logged. |
If either is missing, the server prints a clear message to stderr and exits
immediately (process.exit(1)) — it never starts half-configured.
Argument names are camelCase; the server maps them to the API's snake_case JSON fields for you.
list_posts — page?, perPage? (max 100), status? (draft |
published).
get_post — id (required).
create_post — title (required, ≤255 chars), slug?, contentHtml?,
contentJson? (TipTap ProseMirror document — prefer contentHtml unless
you need this), excerpt? (≤500), status? (draft default | published),
tags? (string array), seoTitle? (≤60), seoDescription? (≤160).
update_post — id (required) + any of the create_post fields
(all optional here). At least one field besides id is required — the tool
rejects a no-op call before making any network request.
delete_post — id (required). Permanent.
publish_post / unpublish_post — id (required). Shorthand for
update_post({ status: "published" }) / update_post({ status: "draft" }).
list_media — page?, perPage?, type? (MIME type prefix, e.g.
"image").
list_comments — page?, perPage?, postId?, status? (approved
| pending | spam).
moderate_comment — id (required), status (required: approved |
pending | spam).
list_members — page?, perPage?, tier? (free | paid).
get_site_settings — no arguments.
The VeloCMS API returns a consistent JSON error envelope:
This client surfaces that message directly (never a raw stack trace), enriched with actionable hints:
UNAUTHORIZED) — the message tells you to check VELOCMS_API_KEY.PLAN_UPGRADE_REQUIRED) — the message points at /admin/billing.INVALID_SCOPE/FORBIDDEN) — the message tells you to check the
key's scopes.RATE_LIMITED) — the Retry-After response header (seconds) is
parsed and included in the error message, and returned as
retryAfterSeconds if you're calling the client library directly.code + message are surfaced as-is.Rate limits are plan-based (Pro: 30/min, 1,000/hr · Business: 120/min, 5,000/hr · Agency: 300/min, 20,000/hr) — this server does not retry automatically; it fails fast with the wait time so an interactive tool call never blocks silently.
list_members are masked by the API itself
(e.g. u***@example.com) — this server never sees or handles unmasked
member PII.get_site_settings by the API — there is no way to read them
through this server.moderate_comment's body field is status, not action —
PATCH /api/v1/comments/{id}/moderate takes { "status": "approved" | "pending" | "spam" } per the API's own schema, so the tool's input is
named to match.get_post and get_site_settings return the record directly (not
wrapped in { "data": ... }) — only the write endpoints (create_post,
update_post, moderate_comment) wrap their response, matching the API's
own inconsistency here (documented in openapi.yaml).upload_media tool — POST /api/v1/media takes
multipart/form-data, which doesn't map cleanly onto typical MCP client
transports. list_media is available for referencing media already
uploaded through the dashboard. Contributions welcome if you need this.The test suite covers: the Authorization: Bearer header on every request,
each tool's exact method/URL/body mapping, error-code mapping for
401/403/429/500 responses, and the missing-env-var fail-fast path. No test
in this repository makes a real network call.
MIT — see LICENSE.