org.velocms/mcp
Draft, publish, and manage your VeloCMS blog from Claude, Cursor, or any MCP client.
Open source Open in the app JSON README (API)
About
Draft, publish, and manage your VeloCMS blog from Claude, Cursor, or any MCP client.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- org.velocms
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.3
- Last push
- 2026-07-20T00:24:11Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:01:53
- Updated
- 2026-08-29 04:01:53
- Origin id
org.velocms/mcp
README
# @velocms/mcp
An [MCP](https://modelcontextprotocol.io) server for [VeloCMS](https://velocms.org) —
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`](https://velocms.org/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.
## What it does
| 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](#tool-reference) below for full argument lists.
## Setup
### 1. Get a VeloCMS API key
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**.
### 2. Configure your MCP client
You don't need to clone this repo — `npx` fetches and runs it on demand.
#### Claude Code
```bash
claude mcp add velocms \
--env VELOCMS_SITE_URL=https://myblog.velocms.org \
--env VELOCMS_API_KEY=velo_your_64_char_hex_key_here \
-- npx -y -p @velocms/mcp velocms-mcp
```
MCP servers register their tools at session start, so restart your Claude
Code session after adding this.
#### Claude Desktop
Add to your `claude_desktop_config.json` (Settings → Developer → Edit
Config):
```json
{
"mcpServers": {
"velocms": {
"command": "npx",
"args": ["-y", "-p", "@velocms/mcp", "velocms-mcp"],
"env": {
"VELOCMS_SITE_URL": "https://myblog.velocms.org",
"VELOCMS_API_KEY": "velo_your_64_char_hex_key_here"
}
}
}
}
```
Restart Claude Desktop after editing.
#### Cursor / any other MCP client
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.
### 3. Local install (contributing / running from source)
```bash
git clone https://github.com/VeloCMS/velocms-mcp.git
cd velocms-mcp
npm install
npm run build
cp .env.example .env
# edit .env and set VELOCMS_SITE_URL + VELOCMS_API_KEY
VELOCMS_SITE_URL=... VELOCMS_API_KEY=... node dist/index.js
```
## Config reference
| 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.
## Tool reference
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.
## Error handling model
The VeloCMS API returns a consistent JSON error envelope:
```json
{ "error": { "code": "RATE_LIMITED", "message": "...", "details": {} } }
```
This client surfaces that message directly (never a raw stack trace),
enriched with actionable hints:
- **401** (`UNAUTHORIZED`) — the message tells you to check `VELOCMS_API_KEY`.
- **403** (`PLAN_UPGRADE_REQUIRED`) — the message points at `/admin/billing`.
- **403** (`INVALID_SCOPE`/`FORBIDDEN`) — the message tells you to check the
key's scopes.
- **429** (`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.
- **Any other non-2xx** — the API's own `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.
## Security
- Your API key is a **tenant-scoped** credential — it can only reach the
one blog it was issued for, and only the endpoints its scopes allow.
- The key is read once from the environment and never logged, echoed, or
included in any tool output.
- Member emails returned by `list_members` are masked by the API itself
(e.g. `u***@example.com`) — this server never sees or handles unmasked
member PII.
- Encrypted tenant settings (Stripe keys, AI provider keys) are excluded
from `get_site_settings` by the API — there is no way to read them
through this server.
## Notes on this MCP 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`).
- There is currently no `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.
## Development
```bash
npm install
npm run typecheck # tsc --noEmit
npm test # vitest — all tests run against a mocked fetch, no live API calls
npm run build # emits dist/
```
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.
## License
MIT — see [LICENSE](LICENSE).