@writavo/mcp-server
Your Writavo Site's content, inside an AI assistant. Draft a post, set its category and byline,attach an image, schedule it, publish it, all from a conversation.
It speaks the Model Context Protocol over stdio, so it runs as a subprocess of your client ratherthan as a service you host.
Install
{
"mcpServers": {
"writavo": {
"command": "npx",
"args": ["-y", "@writavo/mcp-server"],
"env": { "WRITAVO_API_KEY": "wv_sk_your_key_here" }
}
}
}
Create the key at https://app.writavo.com/settings/api-keys and give it only the scopes you wantthe assistant to have. A key never outranks the person who made it: narrowing your own permissionsnarrows every key you created, on the next request.
Without a key the server still starts and get_api_docs still works, so you can read the wholeAPI reference before signing up.
What it can do
Thirty six tools are compiled from Writavo's published OpenAPI specification, plus two written byhand:
- Articles. List, read, create, update, delete, publish, unpublish, schedule, cancel a schedule.
- Taxonomy and people. Categories, tags and authors: list, read, create, update, delete.
- Media. List, read, update, delete, and
upload_media, which drives the whole three steppresigned upload in one call so the assistant does not have to orchestrate it. - Pipeline. Trigger a run, read its status, read the queue.
- Meta. Site information, content types, plan usage and balances, and
get_api_docs, whichneeds no key at all.
What it will not do without asking
publish_article, schedule_article, every delete_* and trigger_pipeline_run do nothing onthe first call. They describe what would happen and wait for confirm: true, which the assistantcan only set after you have agreed. Publishing puts content on your live site, deleting ispermanent, and a pipeline run spends real credits.
Two things are not reachable from an assistant at all, whatever scopes the key carries:
- API keys. A server that can mint a secret key is a server whose compromise mints secret keys,and the key it would use to do so is in a config file on the same machine.
- Webhooks. An assistant that can repoint delivery URLs can quietly redirect your event stream.
Both stay in the dashboard.
What it never writes down
- Your key is sent to
https://api.writavo.com/v1as a bearer header and to nothing else. Notelemetry, no analytics, no third-party host. The base URL is read from the specification andcannot be repointed offapi.writavo.comby an environment variable. - Every reply, log line and error is passed through a redactor, so a key cannot reach yourtranscript even if the API echoed it back inside an error message.
- Standard output carries protocol messages and nothing else. Every console channel is rebound tostandard error before the server starts, because one stray line on stdout is a droppedconnection.
Errors you might see
Each one is answered with what to change rather than a status code.
| Code | What it means | What to do |
|---|---|---|
INSUFFICIENT_SCOPE |
The key lacks the scope, or its creator's permissions no longer cover it | Add the scope at https://app.writavo.com/settings/api-keys |
NOT_ENTITLED |
Your plan does not include the capability | Upgrade at https://app.writavo.com/billing |
INSUFFICIENT_CREDITS |
The organisation cannot afford the next unit of work | Top up at https://app.writavo.com/billing |
SPEND_CAP_REACHED |
This Site hit the monthly ceiling you set for it | Raise the cap or wait for the reset |
NOT_FOUND |
No such object, or it belongs to a different Site | Check you are using the key for the right Site |
The full catalog is in get_api_docs under errors, and at https://writavo.com/docs/errors.
Prompts
- draft-article. Research a topic and write a draft in your Site's own voice. It neverpublishes or schedules.
- publish-checklist. Walk an existing draft through title, slug, SEO fields, excerpt, category,author and featured image, then ask before publishing.
Development
This package lives in the Writavo monorepo. Its tool schemas, descriptions and reference text aregenerated, not written:
npm run gen regenerate from the vendored openapi.yaml
npm test run the 44 offline smoke checks
npm run gen:check fails if the committed tool surface is stale
Adding an endpoint to openapi.yaml and regenerating is the whole of adding a tool. Editinganything under src/generated/ fails CI.
Licence
MIT (LICENSE). Fork it, modify it, vendor it, ship it inside something else.
The MIT grant covers this client package only. It is not a licence to the Writavo Content APIthat the package calls, or to any other part of Writavo. Using the API still requires your owncredentials and is governed by the terms at https://writavo.com/terms, and openapi.yaml (thespecification this package is compiled from) remains the proprietary contract it always was.
That split is deliberate. This package is a thin, generated client: there is nothing in it worthrestricting, and an MIT client is easier to trust, audit, package and list in a registry. Theproduct is the API behind it.