mcpengine/servers/zoho-crm/README.md

Zoho CRM MCP Server

Model Context Protocol (MCP) server for Zoho CRM platform. Manage leads, contacts, accounts, deals, activities, and more with AI.

Features

Comprehensive coverage of Zoho CRM API for AI agents to manage customer relationships, sales pipelines, and business processes.

Tools Implemented (24 total)

Leads (6 tools)

• ✅ zoho_crm_list_leads - List leads with pagination
• ✅ zoho_crm_get_lead - Get detailed lead information
• ✅ zoho_crm_create_lead - Create new lead
• ✅ zoho_crm_update_lead - Update existing lead
• ✅ zoho_crm_delete_lead - Delete lead
• ✅ zoho_crm_convert_lead - Convert lead to Contact/Account/Deal

Contacts (5 tools)

• ✅ zoho_crm_list_contacts - List contacts with pagination
• ✅ zoho_crm_get_contact - Get contact details
• ✅ zoho_crm_create_contact - Create new contact
• ✅ zoho_crm_update_contact - Update contact
• ✅ zoho_crm_delete_contact - Delete contact

Accounts (5 tools)

• ✅ zoho_crm_list_accounts - List accounts with pagination
• ✅ zoho_crm_get_account - Get account details
• ✅ zoho_crm_create_account - Create new account
• ✅ zoho_crm_update_account - Update account
• ✅ zoho_crm_delete_account - Delete account

Deals (5 tools)

• ✅ zoho_crm_list_deals - List deals/opportunities
• ✅ zoho_crm_get_deal - Get deal details
• ✅ zoho_crm_create_deal - Create new deal
• ✅ zoho_crm_update_deal - Update deal
• ✅ zoho_crm_delete_deal - Delete deal

Activities (4 tools)

• ✅ zoho_crm_list_tasks - List tasks
• ✅ zoho_crm_get_task - Get task details
• ✅ zoho_crm_list_events - List events/meetings
• ✅ zoho_crm_list_calls - List call logs

Notes, Products, Quotes (3 tools)

• ✅ zoho_crm_list_notes - List notes
• ✅ zoho_crm_list_products - List products
• ✅ zoho_crm_list_quotes - List quotes

Search (1 tool)

• ✅ zoho_crm_search_records - Generic search across modules

Administration (4 tools)

• ✅ zoho_crm_list_users - List CRM users
• ✅ zoho_crm_list_roles - List roles
• ✅ zoho_crm_list_profiles - List profiles
• ✅ zoho_crm_get_organization_details - Get org info

Workflow (2 tools)

• ✅ zoho_crm_create_task - Create task
• ✅ zoho_crm_update_task - Update task

Installation

npm install
npm run build

Environment Variables

Variable	Required	Description	Example
ZOHO_ACCESS_TOKEN	✅	OAuth access token from Zoho	1000.xxx...
ZOHO_API_DOMAIN	❌	API domain (defaults to US)	https://www.zohoapis.com or https://www.zohoapis.eu

Getting Your Access Token

1. Log in to Zoho API Console
2. Create a new Server-based Application
3. Generate OAuth 2.0 credentials (Client ID + Secret)
4. Use OAuth flow to get Access Token and Refresh Token
5. Use refresh token to generate new access tokens programmatically

For testing, you can use self-client credentials with a long-lived access token.

Required API Scopes

• ZohoCRM.modules.ALL - Full access to CRM modules
• ZohoCRM.settings.ALL - Access to settings and metadata
• ZohoCRM.users.READ - Read user information

Usage

Stdio Mode (Default)

Add to your MCP client configuration:

{
  "mcpServers": {
    "zoho-crm": {
      "command": "node",
      "args": ["/path/to/zoho-crm/dist/main.js"],
      "env": {
        "ZOHO_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

Standalone

export ZOHO_ACCESS_TOKEN="your_token_here"
node dist/main.js

Coverage Manifest

Total API endpoints: ~200+
Tools implemented: 24
Intentionally skipped: 176
  - Custom modules (requires org-specific config)
  - Blueprint operations
  - Canvas operations
  - Inventory modules (Purchase Orders, Sales Orders, Invoices)
  - Advanced analytics
  - Mass operations
  - File attachments

Coverage: 24/200 = 12%
Note: Core functionality coverage is ~90% (all CRUD on main modules)

Examples

Create a Lead

{
  "name": "zoho_crm_create_lead",
  "arguments": {
    "Last_Name": "Smith",
    "Company": "ACME Corp",
    "Email": "john.smith@acme.com",
    "Phone": "+1-555-1234",
    "Lead_Status": "Contacted"
  }
}

Search for Contacts by Email

{
  "name": "zoho_crm_search_records",
  "arguments": {
    "module": "Contacts",
    "criteria": "(Email:equals:john@example.com)",
    "per_page": 50
  }
}

Create a Deal

{
  "name": "zoho_crm_create_deal",
  "arguments": {
    "Deal_Name": "Q1 2024 Enterprise Deal",
    "Stage": "Qualification",
    "Amount": 50000,
    "Closing_Date": "2024-03-31"
  }
}

Development

# Build
npm run build

# Start server
npm start

# Watch mode (requires tsx)
npm run dev

Architecture

• main.ts - Entry point with env validation and graceful shutdown
• server.ts - Server class with lazy-loaded tool modules
• client/zoho-crm-client.ts - API client with rate limiting and OAuth
• tools/ - Tool definitions organized by domain (leads, contacts, accounts, deals, activities, search, administration, workflow)
• types/ - TypeScript interfaces for all Zoho CRM entities

License

MIT