zoho-books-mcp

# zoho-books-mcp A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that gives Claude (and any MCP-compatible AI assistant) full access to the [Zoho Books](https://www.zoho.com/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) ```bash npx zoho-books-mcp ``` ### Option 2 — Global install ```bash npm install -g zoho-books-mcp zoho-books-mcp ``` ### Option 3 — From source ```bash 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](https://api-console.zoho.com) 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) ```bash 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` ```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 ```bash claude mcp add zoho-books -- npx -y zoho-books-mcp ``` Then set your credentials: ```bash 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): ```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" } } } } ``` --- ## 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 ```bash # 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](https://www.zoho.com/books/) account with API access - A valid OAuth 2.0 access token --- ## License MIT — see [LICENSE](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](https://www.zoho.com/books/api/v3/) - [Zoho API Console](https://api-console.zoho.com) - [Model Context Protocol](https://modelcontextprotocol.io) - [MCP SDK on npm](https://www.npmjs.com/package/@modelcontextprotocol/sdk)