Zoho CRM + Books MCP Server

A unified Model Context Protocol (MCP) server that provides seamless integration between Zoho CRM and Zoho Books, enabling AI assistants like Claude to interact with both systems through standardized tools and resources.

Features

CRM Integration: Full access to Zoho CRM modules, records, and operations
Books Integration: Complete Zoho Books customer and invoice management
Data Synchronization: Automated sync between CRM accounts and Books customers
Invoice Creation: Generate Books invoices directly from CRM deals
Universal Search: Search across both CRM and Books data
Multi-Configuration System: Manage multiple OAuth configurations for different environments and projects
OAuth 2.0 Authentication: Secure, token-based authentication
Rate Limiting: Built-in rate limiting and error handling
TypeScript: Full type safety and excellent developer experience

Prerequisites

Node.js 18.0.0 or higher
Zoho CRM account with API access
Zoho Books account with API access
Zoho OAuth application credentials

Installation

Clone the repository:

git clone <repository-url>
cd zoho-mcp-server

Install dependencies:

npm install

Copy the environment configuration:

cp .env.example .env

Configure your environment variables in .env:

Single Configuration (Legacy)

# Zoho OAuth Configuration
ZOHO_CLIENT_ID=your_client_id_here
ZOHO_CLIENT_SECRET=your_client_secret_here
ZOHO_REDIRECT_URI=http://localhost:3000/callback
ZOHO_REFRESH_TOKEN=your_refresh_token_here

# Zoho Data Center (com, eu, in, com.au, jp)
ZOHO_DATA_CENTER=com

# Zoho Books Organization ID (required for Books functionality)
ZOHO_BOOKS_ORGANIZATION_ID=your_organization_id_here

# Zoho API Scopes
ZOHO_SCOPES=ZohoCRM.modules.ALL,ZohoCRM.settings.ALL,ZohoBooks.fullaccess.all

Multi-Configuration System (Recommended)

# Enable multi-configuration system
MULTI_CONFIG_ENABLED=true

# Current environment to use
MULTI_CONFIG_ENVIRONMENT=default

# Path to configuration file (optional)
MULTI_CONFIG_PATH=./zoho-config.json

# Legacy variables (for backward compatibility)
ZOHO_CLIENT_ID=your_client_id_here
ZOHO_CLIENT_SECRET=your_client_secret_here
ZOHO_REDIRECT_URI=http://localhost:3000/callback
ZOHO_REFRESH_TOKEN=your_refresh_token_here
ZOHO_DATA_CENTER=com
ZOHO_BOOKS_ORGANIZATION_ID=your_organization_id_here
ZOHO_SCOPES=ZohoCRM.modules.ALL,ZohoCRM.settings.ALL,ZohoBooks.fullaccess.all

For detailed multi-configuration setup, see MULTI_CONFIG_GUIDE.md.

Zoho OAuth Setup

Go to the Zoho Developer Console
Create a new "Server-based Applications"
Set redirect URI to http://localhost:3000/callback
Note your Client ID and Client Secret
Generate a refresh token using the authorization flow

Build and Run

Build the TypeScript code:

npm run build

Start the server:

npm start

For development with auto-reload:

npm run dev

MCP Integration

Claude Desktop Configuration

Add the following to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "zoho-crm-books": {
      "command": "node",
      "args": ["C:\\zoho-mcp-server\\dist\\server.js"],
      "env": {
        "ZOHO_CLIENT_ID": "your_client_id",
        "ZOHO_CLIENT_SECRET": "your_client_secret",
        "ZOHO_REFRESH_TOKEN": "your_refresh_token",
        "ZOHO_DATA_CENTER": "com",
        "ZOHO_BOOKS_ORGANIZATION_ID": "your_org_id"
      }
    }
  }
}

VS Code Configuration

Add to your VS Code MCP configuration:

{
  "servers": {
    "zoho-crm-books": {
      "command": "node",
      "args": ["C:\\zoho-mcp-server\\dist\\server.js"]
    }
  }
}

Available Tools

CRM & Books Integration Tools

1. sync_accounts_to_customers

Synchronizes CRM accounts to Books customers.

Parameters:

source_module: "accounts" (fixed)
target_module: "customers" (fixed)
filters (optional):
- limit: Number of records to process (1-200)
- page: Page number to process

Example:

{
  "source_module": "accounts",
  "target_module": "customers",
  "filters": {
    "limit": 50,
    "page": 1
  }
}

1.1. sync_contacts_to_customers

Synchronizes CRM contacts to Books customers (bi-directional sync).

Parameters:

source_module: "contacts" (fixed)
target_module: "customers" (fixed)
filters (optional):
- limit: Number of records to process (1-200)
- page: Page number to process

Example:

{
  "source_module": "contacts",
  "target_module": "customers",
  "filters": {
    "limit": 50,
    "page": 1
  }
}

1.2. sync_customers_to_contacts

Synchronizes Books customers to CRM contacts (bi-directional sync).

Parameters:

source_module: "customers" (fixed)
target_module: "contacts" (fixed)
filters (optional):
- limit: Number of records to process (1-200)
- page: Page number to process

Example:

{
  "source_module": "customers",
  "target_module": "contacts",
  "filters": {
    "limit": 50,
    "page": 1
  }
}

2. create_invoice_from_deal

Creates a Books invoice from a CRM deal.

Parameters:

deal_id: CRM deal ID (required)
customer_id: Books customer ID (optional)
invoice_date: Invoice date (optional, defaults to today)
due_date: Due date (optional, defaults to 30 days from today)
include_line_items: Include deal amount as line item (default: true)
send_email: Send invoice email to customer (default: false)

Example:

{
  "deal_id": "123456789",
  "customer_id": "987654321",
  "include_line_items": true,
  "send_email": true
}

3. search_records

Search across CRM and Books records.

Parameters:

module: Module to search ("accounts", "contacts", "deals", "leads", "customers", "invoices")
criteria: Search criteria (required)
fields: Fields to return (optional)
page: Page number (default: 1)
per_page: Results per page (default: 20, max: 200)

Example:

{
  "module": "accounts",
  "criteria": "tech company",
  "fields": ["Account_Name", "Email", "Phone"],
  "page": 1,
  "per_page": 10
}

Books Items Management Tools

4. books_get_items

Get all items from Books with optional filtering and pagination.

Parameters:

page: Page number (default: 1)
per_page: Results per page (default: 20, max: 200)
search_text: Search text (optional)
filter_by: Filter criteria (optional)
sort_column: Column to sort by (optional)
sort_order: Sort order "A" or "D" (optional)

5. books_get_item

Get a specific item from Books by ID.

Parameters:

item_id: Item ID (required)

6. books_create_item

Create a new item in Books.

Parameters:

name: Item name (required)
description: Item description (optional)
rate: Item rate (optional)
unit: Unit of measurement (optional)
sku: Stock keeping unit (optional)
product_type: Product type (optional)
is_taxable: Whether item is taxable (optional)
tax_id: Tax ID (optional)
item_type: Item type (optional)

7. books_update_item

Update an existing item in Books.

Parameters:

item_id: Item ID (required)
Plus any fields from books_create_item to update

8. books_delete_item

Delete an item from Books.

Parameters:

item_id: Item ID (required)

Books Estimates Management Tools

9. books_get_estimates

Get all estimates from Books with optional filtering and pagination.

Parameters:

page: Page number (default: 1)
per_page: Results per page (default: 20, max: 200)
customer_id: Filter by customer ID (optional)
status: Filter by status (optional)
search_text: Search text (optional)
filter_by: Filter criteria (optional)
sort_column: Column to sort by (optional)
sort_order: Sort order "A" or "D" (optional)

10. books_create_estimate

Create a new estimate in Books.

Parameters:

customer_id: Customer ID (required)
line_items: Array of line items (required)
- name: Item name (required)
- quantity: Quantity (required)
- rate: Rate (required)
- description: Description (optional)
- unit: Unit (optional)
- item_id: Item ID (optional)
- tax_id: Tax ID (optional)
estimate_date: Estimate date (optional)
expiry_date: Expiry date (optional)
currency_code: Currency code (optional)
discount: Discount amount (optional)
notes: Notes (optional)
terms: Terms (optional)

11. books_convert_estimate_to_invoice

Convert a Books estimate to an invoice.

Parameters:

estimate_id: Estimate ID (required)

Books Payments Management Tools

12. books_get_payments

Get all payments from Books with optional filtering and pagination.

Parameters:

page: Page number (default: 1)
per_page: Results per page (default: 20, max: 200)
customer_id: Filter by customer ID (optional)
search_text: Search text (optional)
filter_by: Filter criteria (optional)
sort_column: Column to sort by (optional)
sort_order: Sort order "A" or "D" (optional)

13. books_create_payment

Create a new payment in Books.

Parameters:

customer_id: Customer ID (required)
payment_mode: Payment mode (required)
amount: Payment amount (required)
date: Payment date (required)
invoices: Array of invoices to apply payment to (required)
- invoice_id: Invoice ID (required)
- invoice_number: Invoice number (required)
- amount_applied: Amount applied to invoice (required)
- tax_amount_withheld: Tax amount withheld (optional)
reference_number: Reference number (optional)
description: Payment description (optional)
bank_charges: Bank charges (optional)
currency_code: Currency code (optional)
exchange_rate: Exchange rate (optional)

CRM Activities Management Tools

14. crm_get_tasks

Get all tasks from CRM with optional filtering and pagination.

Parameters:

page: Page number (default: 1)
per_page: Results per page (default: 20, max: 200)
sort_by: Column to sort by (optional)
sort_order: Sort order "asc" or "desc" (optional)
status: Filter by status (optional)
due_date: Filter by due date (optional)

15. crm_create_task

Create a new task in CRM.

Parameters:

Subject: Task subject (required)
Status: Task status (optional)
Priority: Task priority (optional)
Due_Date: Due date (optional)
What_Id: Related record ID (optional)
Who_Id: Contact ID (optional)
Description: Task description (optional)
Related_To: Related to field (optional)
Remind_At: Reminder time (optional)
Recurring_Activity: Recurring activity settings (optional)

16. crm_get_events

Get all events from CRM with optional filtering and pagination.

Parameters:

page: Page number (default: 1)
per_page: Results per page (default: 20, max: 200)
sort_by: Column to sort by (optional)
sort_order: Sort order "asc" or "desc" (optional)
start_date: Filter by start date (optional)
end_date: Filter by end date (optional)

17. crm_create_event

Create a new event in CRM.

Parameters:

Subject: Event subject (required)
Start_DateTime: Start date and time (required)
End_DateTime: End date and time (required)
Description: Event description (optional)
Location: Event location (optional)
What_Id: Related record ID (optional)
Who_Id: Contact ID (optional)
Event_Title: Event title (optional)
All_day: All-day event flag (optional)
Participants: Array of participant IDs (optional)
Remind_At: Reminder time (optional)
Recurring_Activity: Recurring activity settings (optional)

18. crm_get_notes

Get notes for a specific CRM record.

Parameters:

module: CRM module name (required)
record_id: Record ID (required)
page: Page number (default: 1)
per_page: Results per page (default: 20, max: 200)

19. crm_create_note

Create a new note for a CRM record.

Parameters:

module: CRM module name (required)
record_id: Record ID (required)
Note_Title: Note title (required)
Note_Content: Note content (required)
Parent_Id: Parent record ID (optional)

20. crm_send_email

Send email for a CRM record.

Parameters:

module: CRM module name (required)
record_id: Record ID (required)
to: Array of recipient email addresses (required)
subject: Email subject (required)
content: Email content (required)
cc: Array of CC email addresses (optional)
bcc: Array of BCC email addresses (optional)
mail_format: Email format (optional)
template_id: Email template ID (optional)

21. crm_get_attachments

Get attachments for a CRM record.

Parameters:

module: CRM module name (required)
record_id: Record ID (required)
page: Page number (default: 1)
per_page: Results per page (default: 20, max: 200)

Configuration Management Tools

22. config_list_environments

List all available environments in the multi-configuration system.

Parameters: None

Example:

{
  "name": "config_list_environments",
  "arguments": {}
}

23. config_switch_environment

Switch to a different environment.

Parameters:

environmentName: Name of the environment to switch to (required)

Example:

{
  "name": "config_switch_environment",
  "arguments": {
    "environmentName": "production"
  }
}

24. config_list_profiles

List all profiles in the current environment.

Parameters: None

Example:

{
  "name": "config_list_profiles",
  "arguments": {}
}

25. config_switch_profile

Switch to a different profile within the current environment.

Parameters:

profileName: Name of the profile to switch to (required)

Example:

{
  "name": "config_switch_profile",
  "arguments": {
    "profileName": "backup"
  }
}

26. config_add_profile

Add a new profile to the current environment.

Parameters:

name: Profile name (required)
description: Profile description (optional)
clientId: Zoho Client ID (required)
clientSecret: Zoho Client Secret (required)
redirectUri: Redirect URI (required)
refreshToken: Refresh Token (required)
dataCenter: Data Center (required)
scopes: Array of API scopes (required)
organizationId: Books Organization ID (optional)

Example:

{
  "name": "config_add_profile",
  "arguments": {
    "name": "backup",
    "description": "Backup production account",
    "clientId": "1000.BACKUP_CLIENT_ID",
    "clientSecret": "BACKUP_CLIENT_SECRET",
    "redirectUri": "https://yourdomain.com/callback",
    "refreshToken": "1000.BACKUP_REFRESH_TOKEN",
    "dataCenter": "com",
    "scopes": [
      "ZohoCRM.modules.ALL",
      "ZohoCRM.settings.ALL",
      "ZohoBooks.fullaccess.all"
    ],
    "organizationId": "BACKUP_ORG_ID"
  }
}

27. config_remove_profile

Remove a profile from the current environment.

Parameters:

profileName: Name of the profile to remove (required)

Example:

{
  "name": "config_remove_profile",
  "arguments": {
    "profileName": "old-profile"
  }
}

28. config_update_profile

Update an existing profile.

Parameters:

profileName: Name of the profile to update (required)
updates: Object containing fields to update (required)

Example:

{
  "name": "config_update_profile",
  "arguments": {
    "profileName": "primary",
    "updates": {
      "description": "Updated description",
      "refreshToken": "1000.NEW_REFRESH_TOKEN"
    }
  }
}

29. config_get_status

Get current configuration status.

Parameters: None

Example:

{
  "name": "config_get_status",
  "arguments": {}
}

30. config_export_to_env

Export current configuration to .env format.

Parameters:

profileName: Name of the profile to export (optional, defaults to active profile)

Example:

{
  "name": "config_export_to_env",
  "arguments": {
    "profileName": "primary"
  }
}

31. config_add_environment

Add a new environment.

Parameters:

name: Environment name (required)
description: Environment description (optional)

Example:

{
  "name": "config_add_environment",
  "arguments": {
    "name": "staging",
    "description": "Staging environment for testing"
  }
}

32. config_remove_environment

Remove an environment.

Parameters:

name: Name of the environment to remove (required)

Example:

{
  "name": "config_remove_environment",
  "arguments": {
    "name": "old-environment"
  }
}

Available Resources

1. zoho://crm/modules

Returns all available CRM modules and their configurations.

2. zoho://books/organizations

Returns Books organization information.

Usage Examples

Claude Desktop Integration

Once configured, you can use the server with Claude Desktop:

@zoho-crm-books sync_accounts_to_customers with limit 10

@zoho-crm-books create_invoice_from_deal for deal ID 123456789

@zoho-crm-books search_records in accounts for "technology"

Programming Interface

You can also use the server programmatically:

import { ZohoMCPServer } from './src/server';

const server = new ZohoMCPServer();
await server.start();

Error Handling

The server includes comprehensive error handling:

Authentication Errors: Automatic token refresh on 401 errors
Rate Limiting: Exponential backoff on 429 errors
Validation Errors: Input validation with detailed error messages
Network Errors: Retry logic with configurable timeouts

Monitoring and Logging

The server includes built-in monitoring:

Request/response logging
Performance metrics
Error tracking
Health checks

Security

OAuth 2.0 token-based authentication
Secure token storage and refresh
Input validation and sanitization
Rate limiting protection
HTTPS enforcement

Development

Project Structure

src/
├── auth/               # OAuth authentication
├── clients/            # API clients (CRM, Books)
├── tools/              # MCP tools implementation
├── resources/          # MCP resources implementation
├── types/              # TypeScript type definitions
└── server.ts           # Main server implementation

Testing

Run tests with:

npm test

Linting

npm run lint

Formatting

npm run format

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

Create an issue on GitHub
Check the Zoho API documentation
Review the MCP specification

Changelog

v1.0.0

Initial release
CRM and Books integration
OAuth 2.0 authentication
Basic sync functionality
MCP server implementation

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
config		config
docs		docs
examples		examples
src		src
tests		tests
.env.example		.env.example
.env.test		.env.test
.gitignore		.gitignore
README.md		README.md
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
zoho-config.json		zoho-config.json

Mgabr90/zoho-mcp-server

Folders and files

Latest commit

History

Repository files navigation

Zoho CRM + Books MCP Server

Features

Prerequisites

Installation

Single Configuration (Legacy)

Multi-Configuration System (Recommended)

Zoho OAuth Setup

Build and Run

MCP Integration

Claude Desktop Configuration

VS Code Configuration

Available Tools

CRM & Books Integration Tools

1. sync_accounts_to_customers

1.1. sync_contacts_to_customers

1.2. sync_customers_to_contacts

2. create_invoice_from_deal

3. search_records

Books Items Management Tools

4. books_get_items

5. books_get_item

6. books_create_item

7. books_update_item

8. books_delete_item

Books Estimates Management Tools

9. books_get_estimates

10. books_create_estimate

11. books_convert_estimate_to_invoice

Books Payments Management Tools

12. books_get_payments

13. books_create_payment

CRM Activities Management Tools

14. crm_get_tasks

15. crm_create_task

16. crm_get_events

17. crm_create_event

18. crm_get_notes

19. crm_create_note

20. crm_send_email

21. crm_get_attachments

Configuration Management Tools

22. config_list_environments

23. config_switch_environment

24. config_list_profiles

25. config_switch_profile

26. config_add_profile

27. config_remove_profile

28. config_update_profile

29. config_get_status

30. config_export_to_env

31. config_add_environment

32. config_remove_environment

Available Resources

1. zoho://crm/modules

2. zoho://books/organizations

Usage Examples

Claude Desktop Integration

Programming Interface

Error Handling

Monitoring and Logging

Security

Development

Project Structure

Testing

Linting

Formatting

Contributing

License

Support

Changelog

v1.0.0

About

Resources

Uh oh!

Stars

Packages