SkanderBS2024/zoho-mcp

Zoho CRM MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with Zoho CRM. This server exposes Zoho CRM functionality as MCP tools that can be used by AI assistants like Claude, GPT, and other MCP-compatible clients.

Features

• Full OAuth2 Authentication: Secure authentication with Zoho CRM using OAuth2 flow
• Environment Variables: Secure credential management using .env files
• Contact Management: Search, create, and update contacts
• Deal Management: Search, create, and list deals
• User Information: Get current user details
• STDIO Transport: Compatible with MCP clients using standard input/output
• Error Handling: Comprehensive error handling with clear error messages
• Token Management: Automatic access token refresh
• PyPI Ready: Installable via pip/uvx for easy distribution

Prerequisites

• Python 3.11 or higher
• Zoho CRM account with API access
• Zoho Developer Console app credentials

Installation

Option 1: Install from PyPI (Recommended)

# Install using uvx (recommended for CLI tools)
uvx zoho-crm-mcp

# Or install using pip
pip install zoho-crm-mcp

Option 2: Install from Source

1. Clone this repository:

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

2. Install dependencies:

   uv sync
   # or
   pip install -e .
   

Setup

Step 1: Create Zoho Developer App

1. Go to Zoho Developer Console
2. Create a new "Server-based Applications" app
3. Note down your Client ID and Client Secret
4. Set redirect URI to http://localhost:8080/callback

Step 2: Configure Environment Variables

Create a .env file in your working directory:

# Copy the example file
cp .env.example .env

Edit .env with your credentials:

ZOHO_CLIENT_ID=your_actual_client_id
ZOHO_CLIENT_SECRET=your_actual_client_secret
ZOHO_REDIRECT_URI=http://localhost:8080/callback
ZOHO_API_DOMAIN=https://www.zohoapis.com
ZOHO_SCOPE=ZohoCRM.modules.ALL,ZohoCRM.users.READ

Authentication Setup

Before running the MCP server, you need to generate authentication tokens manually:

Step 1: Generate Tokens

Run the authentication helper to generate your tokens:

# Using uvx (recommended)
uvx --from zoho-crm-mcp zoho-mcp-auth

# Or if installed locally via pip
zoho-mcp-auth

# Or using uv from source
uv run zoho-mcp-auth

This will guide you through the OAuth flow:

🔐 Zoho CRM Manual Token Generation
===================================

Step 1: Visit the authorization URL
====================================
Please visit this URL to authorize the application:

https://accounts.zoho.com/oauth/v2/auth?scope=ZohoCRM.modules.ALL%2CZohoCRM.users.ALL%2CZohoCRM.org.ALL&client_id=your_client_id&response_type=code&redirect_uri=https%3A%2F%2Flocalhost&access_type=offline

Step 2: Get the authorization code
==================================
After authorization, you'll be redirected to your redirect_uri.
Copy the 'code' parameter from the redirect URL and paste it below.

Enter authorization code: [paste your code here]

✅ Token generation successful!

Step 3: Add tokens to your .env file
====================================
Add the following lines to your .env file:

ZOHO_ACCESS_TOKEN=your_generated_access_token
ZOHO_REFRESH_TOKEN=your_generated_refresh_token

Step 2: Add Tokens to .env File

Copy the generated tokens and add them to your .env file:

# Authentication Tokens
ZOHO_ACCESS_TOKEN=your_generated_access_token_here
ZOHO_REFRESH_TOKEN=your_generated_refresh_token_here

⚠️ Important: Keep these tokens secure and never commit them to version control!

Running the MCP Server

Once your tokens are configured, you can run the server:

# Using uvx (recommended)
uvx --from zoho-crm-mcp zoho-mcp

# Or if installed locally via pip
zoho-mcp

# Or using uv from source
uv run zoho-mcp

The server will validate your authentication and start:

Fetching user information...
✓ Authenticated as: Your Name (your.email@example.com)
Zoho CRM MCP Server running on stdio

Available MCP Tools

1. get_contact_by_email_tool

Search for a contact by email address.

Parameters:

• email (string): Email address to search for

Returns:

• Contact information including ID, name, phone, account, and timestamps

2. create_contact_tool

Create a new contact in Zoho CRM.

Parameters:

• first_name (string): Contact's first name
• last_name (string): Contact's last name
• email (string): Contact's email address
• phone (string): Contact's phone number

Returns:

• Created contact ID and status

3. get_deal_by_name_tool

Search for a deal by name.

Parameters:

• deal_name (string): Name of the deal to search for

Returns:

• Deal information including ID, amount, stage, contacts, and dates

4. create_deal_tool

Create a new deal in Zoho CRM.

Parameters:

• deal_name (string): Name of the deal
• contact_id (string): ID of the associated contact
• stage (string): Deal stage (e.g., 'Qualification', 'Proposal', 'Negotiation', 'Closed Won')
• amount (float): Deal amount

Returns:

• Created deal ID and status

5. update_contact_tool

Update a specific field of an existing contact.

Parameters:

• contact_id (string): ID of the contact to update
• field (string): Field name to update (e.g., 'Phone', 'Email', 'First_Name')
• value (string): New value for the field

Returns:

• Update status and confirmation

6. list_open_deals_tool

List all open deals (excluding closed deals).

Parameters: None

Returns:

• Array of open deals with details

7. get_user_info_tool

Get current authenticated user information.

Parameters: None

Returns:

• User information including name, email, role, and profile

Usage with MCP Clients

Claude Desktop

Add this server to your Claude Desktop configuration:

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

{
  "mcpServers": {
    "zoho-crm": {
      "command": "uvx",
      "args": ["--from", "zoho-crm-mcp", "zoho-mcp"],
      "env": {
        "ZOHO_CLIENT_ID": "your_zoho_client_id",
        "ZOHO_CLIENT_SECRET": "your_zoho_client_secret",
        "ZOHO_REDIRECT_URI": "http://localhost:8080/callback",
        "ZOHO_API_DOMAIN": "https://www.zohoapis.com",
        "ZOHO_SCOPE": "ZohoCRM.modules.ALL,ZohoCRM.users.ALL,ZohoCRM.org.ALL",
        "ZOHO_ACCESS_TOKEN": "your_generated_access_token",
        "ZOHO_REFRESH_TOKEN": "your_generated_refresh_token"
      }
    }
  }
}

Alternative configuration if installed locally:

{
  "mcpServers": {
    "zoho-crm": {
      "command": "zoho-mcp",
      "args": [],
      "env": {
        "ZOHO_CLIENT_ID": "your_zoho_client_id",
        "ZOHO_CLIENT_SECRET": "your_zoho_client_secret",
        "ZOHO_REDIRECT_URI": "http://localhost:8080/callback",
        "ZOHO_API_DOMAIN": "https://www.zohoapis.com",
        "ZOHO_SCOPE": "ZohoCRM.modules.ALL,ZohoCRM.users.ALL,ZohoCRM.org.ALL",
        "ZOHO_ACCESS_TOKEN": "your_generated_access_token",
        "ZOHO_REFRESH_TOKEN": "your_generated_refresh_token"
      }
    }
  }
}

Other MCP Clients

For other MCP-compatible clients, configure them to run:

# Using uvx (recommended)
uvx --from zoho-crm-mcp zoho-mcp

# Or if installed locally via pip
zoho-mcp

Error Handling

The server provides comprehensive error handling:

• Authentication errors: Clear messages about missing or invalid credentials
• API errors: Detailed error messages from Zoho CRM API
• Network errors: Connection and timeout error handling
• Data validation: Input parameter validation

All errors are returned in a consistent format:

{
  "error": "Description of the error",
  "details": "Additional error details if available"
}

Security Considerations

Current Implementation (Development)

• Refresh tokens are stored in .env file (plain text)
• Suitable for development and testing

Production Recommendations

• Store refresh tokens in encrypted database
• Use secure key management services (AWS KMS, Azure Key Vault, etc.)
• Implement token rotation policies
• Use environment variables for sensitive configuration
• Enable audit logging
• Implement rate limiting

Extending the Server

To add new tools:

1. Add the function to zoho_mcp/zoho_tools.py:

   def new_tool_function(param1: str, param2: int) -> Dict[str, Any]:
       # Implementation
       pass
   

2. Create MCP tool wrapper in zoho_mcp/server.py:

   @mcp.tool()
   def new_tool(param1: str, param2: int) -> Dict[str, Any]:
       """
       Description of the new tool.
       
       Args:
           param1: Description of parameter 1
           param2: Description of parameter 2
           
       Returns:
           Description of return value
       """
       return new_tool_function(param1, param2)
   

3. Update documentation

Troubleshooting

Common Issues

1. "Missing .env file" error:

   • Create a .env file in your working directory
   • Copy from .env.example and fill in your credentials

2. "Not authenticated" error:

   • Run zoho-mcp-auth to set up authentication
   • Check that your .env file has valid credentials

3. "Token refresh failed":

   • Re-run the OAuth setup process
   • Delete old tokens from .env and re-authenticate

4. "API request failed":

   • Verify your Zoho CRM permissions
   • Check that the API domain is correct for your region

5. "Contact/Deal not found":

   • Verify the search criteria
   • Check that the record exists in your CRM

Environment Variable Issues

1. Missing environment variables:

   • Ensure ZOHO_CLIENT_ID and ZOHO_CLIENT_SECRET are set in .env
   • Check .env.example for the complete list

2. Invalid credentials:

   • Verify your ZOHO_CLIENT_ID and ZOHO_CLIENT_SECRET
   • Ensure they match your Zoho Developer Console app

3. Wrong redirect URI:

   • Ensure ZOHO_REDIRECT_URI matches your Zoho app configuration
   • Default should be http://localhost:8080/callback

4. Authentication flow issues:

   • If authentication fails, delete ZOHO_ACCESS_TOKEN and ZOHO_REFRESH_TOKEN from .env
   • Restart the server to trigger a fresh OAuth flow

Debug Mode

For debugging, you can add logging to see API requests:

import logging
logging.basicConfig(level=logging.DEBUG)

API Rate Limits

Zoho CRM has API rate limits:

• Free edition: 200 API calls per day
• Paid editions: Higher limits based on plan

The server doesn't implement rate limiting, so monitor your usage accordingly.

Support

For issues related to:

• Zoho CRM API: Check Zoho CRM API documentation
• MCP Protocol: Check Model Context Protocol specification
• This server: Check the error messages and logs

License

This project is provided as-is for educational and development purposes.