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

```bash
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](https://api-console.zoho.com/)
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:

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

### Standalone

```bash
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

```json
{
  "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

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

### Create a Deal

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

## Development

```bash
# 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