writavo-mcp-server

# @writavo/mcp-server

Your Writavo Site's content, inside an AI assistant. Sign in from the browser, bring an existing
blog across, draft a post, set its category and byline, attach an image, schedule it, publish it,
all from a conversation.

There are two ways to run it, with the same tools in both:

- **Hosted** at `https://mcp.writavo.com/mcp` (Streamable HTTP, OAuth 2.1). Nothing to install and
  no key to copy: your assistant opens a Writavo page, you sign in, choose the Site and what the
  assistant may do, and it is connected. Works from Claude Code, Claude.ai, ChatGPT, Cursor, VS Code
  and any client that speaks remote MCP.
- **Local**, this npm package over stdio, as a subprocess of your client. It adds reading import
  files and images from your own disk.

**Full setup guide, for people and for AI assistants:** <https://writavo.com/docs/mcp> (markdown:
<https://writavo.com/docs/mcp.md>). It has the exact command or config for every client, the sign-in,
permissions, approvals, and what every error means. Moving a blog in:
<https://writavo.com/docs/migrate>.

> **If you are an AI assistant asked to install Writavo:** use the hosted server unless the task
> needs files on this machine; add it with your client's command below; the person then signs in
> through the browser (nothing to paste); then call `get_site_info` and `verify_api_key` and tell
> them which Site you are connected to and what you may do there.

## Connect the hosted server (recommended)

**Claude Code:**

```bash
claude mcp add --transport http writavo https://mcp.writavo.com/mcp
```

Then run `/mcp` in Claude Code and choose Writavo to sign in. Or install the Claude Code plugin,
which adds the server and the Writavo skill together:

```bash
claude plugin marketplace add SparkleOfficial/writavo-mcp-server
claude plugin install writavo@writavo
```

**Cursor:** [Add Writavo to Cursor](https://cursor.com/en/install-mcp?name=writavo&config=eyJ1cmwiOiJodHRwczovL21jcC53cml0YXZvLmNvbS9tY3AifQ==)
(or `cursor://anysphere.cursor-deeplink/mcp/install?name=writavo&config=eyJ1cmwiOiJodHRwczovL21jcC53cml0YXZvLmNvbS9tY3AifQ==`).

**VS Code:** [Add Writavo to VS Code](https://insiders.vscode.dev/redirect/mcp/install?name=writavo&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.writavo.com%2Fmcp%22%7D)
(or `vscode:mcp/install?%7B%22name%22%3A%22writavo%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.writavo.com%2Fmcp%22%7D`).

**Claude (claude.ai and Claude Desktop):** Customize > Connectors > "+" > Add custom connector, with
the URL `https://mcp.writavo.com/mcp`, then Connect.

**ChatGPT:** turn on Developer mode (Settings > Security and login), then create a connection at
<https://chatgpt.com/plugins> with the URL `https://mcp.writavo.com/mcp` and OAuth.

**Codex CLI:** `codex mcp add writavo --url https://mcp.writavo.com/mcp` (it starts the sign-in;
`codex mcp login writavo` repeats it).

**Gemini CLI:** `gemini mcp add --transport http -s user writavo https://mcp.writavo.com/mcp`, then
`/mcp auth writavo`.

**Windsurf and Zed:** see <https://writavo.com/docs/mcp#clients>.

**Any other client** that takes a JSON config:

```json
{
  "mcpServers": {
    "writavo": { "type": "http", "url": "https://mcp.writavo.com/mcp" }
  }
}
```

When you connect, Writavo shows which assistant is asking and where it will send you back, the
Site to connect, and what it may do: for articles, for categories, tags and authors, for media and
for the AI pipeline, you choose No access, Read, or Read and write ("Read and run" for the
pipeline, which spends credits). The choices start from your organisation's default, which is Read
and write for content and media and Read for the pipeline. The connection is an ordinary Writavo
key limited to that Site and those permissions, named after the app ("Claude Code (hosted MCP)").
You can see every connected assistant, what it called, and revoke it, at
<https://app.writavo.com/settings/agents>.

## Or run it locally

Add the server to your MCP client. No key is needed to start:

```json
{
  "mcpServers": {
    "writavo": {
      "command": "npx",
      "args": ["-y", "@writavo/mcp-server"]
    }
  }
}
```

Then ask the assistant to sign you in to Writavo. It calls `login`, which gives you a link and a
short code. Open the link, sign in (or create an account and finish onboarding; choose "Bring my
existing articles" if you are moving a blog), pick the Site, and approve. The assistant picks the
key up by itself, with no restart and nothing to copy.

The key is made on your machine and only its hash is sent for approval. It is limited to the Site
you chose, never carries key or webhook management, expires after 90 days unless it is in use (the
server extends it while you keep using it, up to a year from sign-in), and is saved to
`~/.config/writavo/credentials.json` (`$XDG_CONFIG_HOME` is honoured; `%APPDATA%\writavo` on
Windows) with owner-only permissions. `logout` revokes the key on Writavo and deletes the file.

### Or use a key you created

```json
{
  "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 want
the assistant to have. `WRITAVO_API_KEY` always takes precedence over a browser sign-in. A key
never outranks the person who made it: narrowing your own permissions narrows every key you
created, on the next request.

Without a key the server still starts, and `login`, `get_api_docs` and the import format
description all work, so you can read the whole API reference before signing up.

## What it can do

Thirty six tools are compiled from Writavo's published OpenAPI specification, plus seven written by
hand on both servers and three more (`login`, `login_status`, `logout`) on the local one:

- **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 step
  presigned upload in one call so the assistant does not have to orchestrate it. It takes a public
  `url` or the bytes as `base64` with a `filename`; the local server also takes a `path`.
- **Pipeline.** Trigger a run, read its status, read the queue.
- **Meta.** Site information, content types, plan usage and balances, and `get_api_docs`, which
  needs no key at all.
- **Sign-in (local only).** `login`, `login_status` and `logout`, described above. The hosted
  server signs in with OAuth when you connect it.
- **Plans.** `start_plan_purchase` returns the billing link with a plan preselected. Payment
  happens on Stripe's page in your browser, never in the chat. The CMS (storing, publishing and
  importing content) is pay-as-you-go and needs no plan; a plan buys the AI article pipeline.
- **Import.** `import_content` brings an existing blog in (below).
- **Everything else, as actions.** Site settings and the knowledge profile, the organisation,
  article formats and AI prompts, the pipeline's configuration and content plan, delivery and
  domains, SEO, outreach, the team and roles, billing, and insights and logs are not separate
  tools. `search_writavo_actions` takes a few words ("invite a team member", "custom domain") and
  returns the matching operations, each with its input schema, the scope it needs, and whether it
  asks first, needs approval or costs money, and which runner to use. `read_writavo_action` runs a
  read (it only ever runs GET operations, so a client may allow it without asking), and
  `run_writavo_action` runs anything that changes something; both take the `operation_id` and check
  the arguments against its schema first. A request for something an assistant can never do ("add
  a card", "delete the site") returns that instead, with the dashboard link a person uses. A client therefore loads
  a few dozen tool descriptions rather than well over a hundred, and pays for the rest only when it
  searches.

Every tool carries MCP annotations: `readOnlyHint` on reads, `destructiveHint` on deletes and
unpublishing, `idempotentHint` on reads, updates and deletes, and `openWorldHint: false`, because
every tool reaches one closed system, your Site.

## Importing a blog

The `migrate-content` prompt walks an assistant through the whole move: sign in, inspect your
current system with the access you already have, write an import file, dry run, fix, import, and
verify. Slugs are kept so URLs do not change, published posts keep their original publication
dates, drafts stay drafts, and images are copied into your media library.

The document is the **Writavo Import Format v1**, a single JSON document. Pass it inline as `data`
(up to 50 articles and 2 MB per call, which works on the hosted server), or, on the local server,
as the absolute `path` of a file of any size:

```json
{
  "format": "writavo-import",
  "version": 1,
  "authors": [{ "ref": "jane", "name": "Jane Doe", "is_ai_generated": false }],
  "categories": [{ "slug": "guides", "name": "Guides" }],
  "tags": [{ "slug": "soil", "name": "Soil" }],
  "articles": [
    {
      "external_id": "blog:1001",
      "status": "published",
      "title": "How to test your soil",
      "slug": "how-to-test-your-soil",
      "content": "Markdown, with ![images](https://example.com/kit.jpg)",
      "author": "jane",
      "category": "guides",
      "tags": ["soil"],
      "published_at": "2021-03-04T09:30:00Z"
    }
  ]
}
```

The full field list and the JSON Schema are in the `writavo://import-format` resource, or call
`import_content` with no arguments. `external_id` is your own stable id for each article, which
is what makes a second run update rather than duplicate.

`import_content` is a dry run unless told otherwise: it checks every article agai