Zenskar MCP Server

MCP server for the Zenskar API. 113 tools covering customers, contracts, invoices, payments, credit notes, accounting, products, plans, entitlements, billable metrics, and more.

What it does

• Customers: list, search, create, update, delete, addresses, contacts, payment methods
• Contracts: create, read, update, delete, amend, add phases and pricing, pause/resume, expire
• Invoices: list, get, approve, void, generate, credit notes, download
• Payments: create, edit, refund, delete, auto-charge
• Credit notes: list, create against invoice, get by ID
• Accounting: chart of accounts, journal entries and lines, balance sheet, income statement, account balances
• Products: CRUD, pricing configurations
• Plans: list, create, add products, preview estimates
• Entitlements: list, get, create, update, delete
• Billable metrics (aggregates): list, get, create, update, delete, schemas, estimates, logs
• Business entities: list, get, create, update
• Jobs: monitor async operations
• Custom attributes and tax categories
• Multi-tenant, supports Bearer token and API key auth

Prerequisites

Before continuing, you need two things:

1. Node.js 20.10 or newer on your machine
2. Zenskar credentials — your Organization ID and an API Key

Node.js

Check whether it's already installed. Open a terminal and run:

node --version
npm --version

This project requires Node.js 20.10 or newer. If both commands print a version that meets this, jump to Zenskar credentials.

If you see command not found or a version older than 20.10, download and install the LTS build from https://nodejs.org/en/download. npm (and npx) ship with Node.js — no separate install needed. After installing, open a new terminal window and re-run node --version to confirm.

Zenskar credentials

You need two values from your Zenskar dashboard. Grab both before moving to Installation.

Organization ID — open https://app.zenskar.com/settings (General tab) and copy your Organization ID.

API Key — open https://app.zenskar.com/settings?tab=api-keys, click Create new API key, give it a name, and copy the key.

Store the API key somewhere safe — the dashboard only shows the full key once. If you lose it, you'll have to create a new one.

Installation

For Claude Desktop App

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "zenskar": {
      "command": "npx",
      "args": ["mcp-zenskar"],
      "env": {
        "ZENSKAR_ORGANIZATION": "your-org-id",
        "ZENSKAR_API_KEY": "your-api-key"
      }
    }
  }
}

You can omit one or both environment variables from the config, but the server will error until Claude supplies them in a tool call. Keeping them in the env block prevents repeated credential prompts.

For Other AI Applications

Install globally:

npm install -g mcp-zenskar

Or run directly:

npx mcp-zenskar

Authentication

Every request needs:

1. Organization ID — set via ZENSKAR_ORGANIZATION
2. API Key — set via ZENSKAR_API_KEY

See Zenskar credentials above for how to get both.

At runtime the server reads these env vars (or accepts them from the MCP client via tool invocation).

Advanced: bearer tokens

Same session token from your browser devtools is also accepted via ZENSKAR_AUTH_TOKEN (sent as Authorization: Bearer ...). Short-lived — API key is preferred for any non-throwaway use. Kept for backward compatibility, so existing configs that use ZENSKAR_AUTH_TOKEN continue to work unchanged.

Usage

In Claude Desktop

Once configured, you can ask Claude to interact with your Zenskar data:

"Show me my recent customers"
"Find the contract for Acme Corp and add a $500/month add-on phase"
"Create a $25 credit note against the latest invoice for customer X"
"Show me the balance sheet and income statement"
"List all products and their pricing configurations"
"Record a $1000 successful manual payment or tax withheld amount against invoice Y"

Available Tools

Customers

Contacts

Contracts

Invoices

Payments

Credit Notes

Products and Pricing

Plans (Templates)

Accounting

Custom Attributes and Tax

Jobs

Business Entities

Customer Addresses and Payment Methods

Metrics and Usage Events

Entitlements

Other

Security

• All requests require a valid organization ID and auth token
• No credentials are stored by the server
• Auth is passed through from the client

Development

This repo uses pnpm for package management. If you don't have it, install it once with npm install -g pnpm (or corepack enable && corepack prepare pnpm@latest --activate).

# Clone the repository
git clone https://github.com/zenskar/mcp-zenskar
cd mcp-zenskar

# Install dependencies
pnpm install

# Build the bundle (produces dist/server.mjs + dist/mcp-config.json)
pnpm run build

# Run the server
pnpm start

Developing Locally Without Publishing

If you want Claude Desktop to use a local checkout instead of the npm package:

# Install dependencies + build the bundle
pnpm install
pnpm run build

# Optional: install the local build globally (requires dist/ from the previous step)
npm install -g .

Then either point Claude to the globally-installed binary (usually $(npm bin -g)/mcp-zenskar) or call the built bundle directly:

{
  "command": "node",
  "args": ["/absolute/path/to/mcp-zenskar/dist/server.mjs"],
  "env": {
    "ZENSKAR_ORGANIZATION": "your-org-id",
    "ZENSKAR_AUTH_TOKEN": "your-token"
  }
}

To iterate on src/server.js without rebuilding, run it directly — npm install already installs the bundler's devDependencies which include the runtime libs:

{
  "command": "node",
  "args": ["/absolute/path/to/mcp-zenskar/src/server.js"]
}

Configuration

The server uses src/mcp-config.json to define available tools and API endpoints. This file contains the complete mapping of MCP tools to Zenskar API operations. All tools are declarative — no code changes needed to add new tools.

License

MIT

Support

For issues and support:

• GitHub Issues: https://github.com/zenskar/mcp-zenskar/issues
• Zenskar Documentation: https://docs.zenskar.com