For developers · Model Context Protocol

Zivvy MCP server

A tiny stdio server that lets Claude, Claude Code, Cursor, and any MCP-aware client read and write your Zivvy workspace — customers, invoices, sales orders, bank transactions — through the public /v1 API.

Install from npm API reference Webhooks

Try it nowbash

npx -y @zivvy/mcp-server

1 · Install

Two ways to run it

Either let npx spawn it on demand, or install once and reference the binary. Both wire the same way.

On-demand with npx

Recommended

Nothing to install globally. The MCP client spawns the server the first time a tool is called.

npx -y @zivvy/mcp-server

Global install

Ship the binary once, reference it as zivvy-mcp in your MCP client config.

npm install -g @zivvy/mcp-server

2 · Configure

Paste, restart, done

Every MCP client uses the same stdio contract. The block below drops into Claude Code, Claude Desktop, Cursor, Cline, or Windsurf — the path to the settings file is the only thing that changes.

Claude Code~/.claude/settings.json

{
  "mcpServers": {
    "zivvy": {
      "command": "npx",
      "args": ["-y", "@zivvy/mcp-server"],
      "env": {
        "ZIVVY_API_KEY": "zk_live_...",
        "ZIVVY_API_BASE": "https://integrate.zivvy.xyz"
      }
    }
  }
}

Restart Claude Code. Type /mcp to confirm the zivvy server is healthy and every tool is listed.

Claude Desktopclaude_desktop_config.json

{
  "mcpServers": {
    "zivvy": {
      "command": "npx",
      "args": ["-y", "@zivvy/mcp-server"],
      "env": { "ZIVVY_API_KEY": "zk_live_..." }
    }
  }
}

On macOS the file lives at ~/Library/Application Support/Claude/. Restart the app.

Environment variables

Variable	Required	Default	Purpose
ZIVVY_API_KEY	yes	—	Per-workspace API key. Create one at /settings/developer.
ZIVVY_API_BASE	no	https://integrate.zivvy.xyz	Override for staging or a self-hosted Zivvy.
ZIVVY_MCP_DEBUG	no	—	Set to `1` to log a single startup line to stderr. Never logs your key.

A missing ZIVVY_API_KEY never crashes the server. Each tool call returns a friendly error so the LLM can surface the fix.

Create an API key

3 · Tools

Twelve tools, one shape

Every tool maps 1:1 to a REST call. The MCP server holds no state and caches nothing — the JSON coming back is exactly what the API returned.

Tool	REST call	Purpose
`list_resources`	GET /v1/resources	Enumerate the resource slugs this API key can address, with tier, module, and submittable flag.
`list_records`	GET /v1/:resource	Paginated list with optional server-side filter and order_by. Only `filterable` fields are honored.
`get_record`	GET /v1/:resource/:id	Fetch a single record by ID — usually the Frappe `name`, or `item_code` for items.
`create_record`	POST /v1/:resource	Create a new record. Submittable docs are created in Draft; call `submit_record` next.
`update_record`	PATCH /v1/:resource/:id	Partial update. `createOnly` fields are rejected. Submitted docs must be cancelled first.
`delete_record`	DELETE /v1/:resource/:id	Delete unsubmitted, non-referenced records. Returns 409 with the linked docs when blocked.
`submit_record`	POST /v1/:resource/:id/submit	Submit a draft document (docstatus 0 → 1). Only for `submittable: true` resources.
`list_addons`	GET /v1/addons	Marketplace add-ons for this workspace, with billing state and price.
`list_tiers`	GET /v1/tiers	Free / Pro / Business tiers, what each includes, and the workspace's current tier.
`subscribe_tier`	POST /v1/tiers/:slug/subscribe	Change tier. Returns a checkout URL when payment is needed; otherwise applies immediately.
`list_events`	GET /v1/events	Event log — created / updated / submitted / paid / cancelled across every resource.
`list_webhook_subscriptions`	GET /v1/webhooks	Webhook subscriptions on this workspace: target URL, subscribed events, last delivery.

Resources (MCP concept)

The server also exposes two resources — read-only URIs the client can pull without calling a tool. Use these when the LLM needs to understand the schema before writing anything.

zivvy://openapi

Full OpenAPI 3.1 spec for the /v1 surface — request/response shapes, required fields, examples.

zivvy://resources

The resource catalog. Cheaper than reading the full OpenAPI when you only need slugs, tiers, and filterables.

4 · Prompts

Try these in Claude

Once the server is wired, ask the model in plain English. It will call `list_resources` and `zivvy://openapi` on its own when it needs the shape.

List the ten most recent unpaid sales invoices for Acme Corp.

Draft a sales order for two units of IT-001 for Acme Corp, then submit it.

Show me every bank transaction from last week that's still unreconciled.

Which add-ons are inactive? Which ones would help a Pro workspace?

5 · Security

What the server sees, what it doesn't

The MCP server is a thin proxy — the same trust posture as calling the API directly, plus the fact that the LLM now sees the responses.

Tenancy

API keys are scoped to a single workspace. A leaked key cannot read another tenant's data — the check happens at the request layer, not in application code.

Transport

Traffic goes directly from your local process to integrate.zivvy.xyz over TLS. No third party sits between the client and Zivvy.

Secrets

The server never logs your API key. ZIVVY_MCP_DEBUG=1 logs only whether a key is present.

The LLM sees responses

Every tool result is JSON the model reads. If a resource contains data you don't want in the model's context, don't call the tool that returns it — the server does not filter fields on your behalf.

Ready to try it?

Grab an API key, paste the config block, and ask Claude to draft an invoice.

Create an API key View on npm Webhooks reference