zoho-books-mcp

A Model Context Protocol (MCP) server that gives Claude (and any MCP-compatible AI assistant) full access to the Zoho Books accounting API.

Manage invoices, bills, contacts, sales orders, purchase orders, payments, journal entries, and more — all through natural language.

Features

• 57 tools covering every major Zoho Books resource
• Works with Claude Desktop, Claude Code, Cursor, and any MCP-compatible client
• OAuth access token authentication — per-request or via environment variable
• Multi-region support: com, eu, in, com.au, sa
• TypeScript-first with Zod runtime validation
• Zero-dependency runtime (only @modelcontextprotocol/sdk and zod)

Tools Reference

| Module | Tools | |---|---| | Organizations | list_organizations, get_organization | | Items | list_items, get_item, create_item, update_item, delete_item, mark_item_active, mark_item_inactive | | Contacts | list_contacts, get_contact, create_contact, update_contact, delete_contact | | Invoices | list_invoices, get_invoice, create_invoice, update_invoice, delete_invoice, mark_invoice_sent, mark_invoice_void, email_invoice | | Customer Payments | list_customer_payments, get_customer_payment, create_customer_payment, delete_customer_payment | | Credit Notes | list_creditnotes, get_creditnote, create_creditnote, delete_creditnote | | Sales Orders | list_salesorders, get_salesorder, create_salesorder, update_salesorder, delete_salesorder, mark_salesorder_open, mark_salesorder_void | | Bills | list_bills, get_bill, create_bill, update_bill, delete_bill | | Vendor Payments | list_vendor_payments, get_vendor_payment, create_vendor_payment | | Purchase Orders | list_purchaseorders, get_purchaseorder, create_purchaseorder, delete_purchaseorder | | Taxes | list_taxes, get_tax, create_tax | | Journals | list_journals, get_journal, create_journal, delete_journal | | Chart of Accounts | list_chart_of_accounts |

Installation

Option 1 — npx (no install required)

npx zoho-books-mcp

Option 2 — Global install

npm install -g zoho-books-mcp
zoho-books-mcp

Option 3 — From source

git clone https://github.com/ossycodes/zoho-books-mcp.git
cd zoho-books-mcp
npm install
npm run build
npm start

Configuration

Get your OAuth access token

Zoho Books uses OAuth 2.0. To get an access token:

1. Go to Zoho API Console
2. Create a Self Client (for personal use) or a Server-based Application
3. Generate an access token with the scope ZohoBooks.fullaccess.all
4. Copy your access token and organization ID (found in Zoho Books under Settings → Organization Profile)

Note: Access tokens expire every hour. Use a refresh token flow or a long-lived token for production use.

Set environment variables (recommended)

export ZOHO_ACCESS_TOKEN=your_access_token_here
export ZOHO_ORGANIZATION_ID=your_organization_id_here

Or add them to your shell profile (~/.zshrc, ~/.bashrc).

Per-request credentials

Every tool also accepts optional access_token and organization_id parameters, which take precedence over environment variables. This is useful when working with multiple Zoho Books organizations.

Region

The server defaults to the com (US/global) data center. Set the region parameter per tool call if your account is on a different data center:

| Region | Data Center | |---|---| | com | United States / Global (default) | | eu | Europe | | in | India | | com.au | Australia | | sa | Saudi Arabia |

Usage with Claude Desktop

Add this to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "zoho-books": {
      "command": "npx",
      "args": ["-y", "zoho-books-mcp"],
      "env": {
        "ZOHO_ACCESS_TOKEN": "your_access_token_here",
        "ZOHO_ORGANIZATION_ID": "your_organization_id_here"
      }
    }
  }
}

Usage with Claude Code

claude mcp add zoho-books -- npx -y zoho-books-mcp

Then set your credentials:

export ZOHO_ACCESS_TOKEN=your_access_token_here
export ZOHO_ORGANIZATION_ID=your_organization_id_here

Usage with Cursor

Add to .cursor/mcp.json in your project root (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "zoho-books": {
      "command": "npx",
      "args": ["-y", "zoho-books-mcp"],
      "env": {
        "ZOHO_ACCESS_TOKEN": "your_access_token_here",
        "ZOHO_ORGANIZATION_ID": "your_organization_id_here"
      }
    }
  }
}

Example Prompts

Once connected, you can ask Claude things like:

• "List all unpaid invoices"
• "Create an invoice for customer ID 123 with 2 units of item 456 at 500 SAR each"
• "Show me all overdue bills"
• "Create a journal entry debiting account 1001 and crediting account 2001 for 10000"
• "List all contacts of type vendor"
• "Email invoice INV-001 to the customer"
• "Create a sales order for customer 789 with shipment date 2026-05-01"
• "List all purchase orders with status open"
• "What taxes are configured in my account?"
• "Show me the chart of accounts"

Development

# Install dependencies
npm install

# Run in development mode (uses ts-node, no build step)
npm run dev

# Build for production
npm run build

# Run built server
npm start

Project Structure

src/
└── index.ts     # All 57 tool definitions and HTTP helpers (single-file server)
dist/
└── index.js     # Compiled & bundled output (generated by `npm run build`)

Adding a New Tool

1. Define a Zod input schema
2. Register the tool with server.tool(name, description, schema, handler)
3. Use the r() helper to call the Zoho Books API
4. Run npm run build

Authentication Details

• Header: Authorization: Zoho-oauthtoken <token>
• Base URL: depends on region, e.g. https://books.zoho.com/api/v3
• Each tool accepts optional access_token, organization_id, and region fields; falls back to ZOHO_ACCESS_TOKEN / ZOHO_ORGANIZATION_ID env vars

Requirements

• Node.js 20+
• A Zoho Books account with API access
• A valid OAuth 2.0 access token

License

MIT — see LICENSE for details.

Contributing

Pull requests are welcome. For major changes, please open an issue first.

1. Fork the repo
2. Create a feature branch (git checkout -b feature/my-tool)
3. Commit your changes
4. Open a pull request

Links

• Zoho Books API Docs
• Zoho API Console
• Model Context Protocol
• MCP SDK on npm