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

Clone this repository:

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

Install dependencies:
```
uv sync
# or
pip install -e .
```

Setup

Step 1: Create Zoho Developer App

Go to Zoho Developer Console
Create a new "Server-based Applications" app
Note down your Client ID and Client Secret
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:

Add the function to zoho_mcp/zoho_tools.py:

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

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)

Update documentation

Troubleshooting

Common Issues

"Missing .env file" error:
- Create a .env file in your working directory
- Copy from .env.example and fill in your credentials
"Not authenticated" error:
- Run zoho-mcp-auth to set up authentication
- Check that your .env file has valid credentials
"Token refresh failed":
- Re-run the OAuth setup process
- Delete old tokens from .env and re-authenticate
"API request failed":
- Verify your Zoho CRM permissions
- Check that the API domain is correct for your region
"Contact/Deal not found":
- Verify the search criteria
- Check that the record exists in your CRM

Environment Variable Issues

Missing environment variables:
- Ensure ZOHO_CLIENT_ID and ZOHO_CLIENT_SECRET are set in .env
- Check .env.example for the complete list
Invalid credentials:
- Verify your ZOHO_CLIENT_ID and ZOHO_CLIENT_SECRET
- Ensure they match your Zoho Developer Console app
Wrong redirect URI:
- Ensure ZOHO_REDIRECT_URI matches your Zoho app configuration
- Default should be http://localhost:8080/callback
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.

Zoho CRM MCP Server

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

Clone this repository:

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

Install dependencies:
```
uv sync
# or
pip install -e .
```

Setup

Step 1: Create Zoho Developer App

Go to Zoho Developer Console
Create a new "Server-based Applications" app
Note down your Client ID and Client Secret
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:

Add the function to zoho_mcp/zoho_tools.py:

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

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)

Update documentation

Troubleshooting

Common Issues

"Missing .env file" error:
- Create a .env file in your working directory
- Copy from .env.example and fill in your credentials
"Not authenticated" error:
- Run zoho-mcp-auth to set up authentication
- Check that your .env file has valid credentials
"Token refresh failed":
- Re-run the OAuth setup process
- Delete old tokens from .env and re-authenticate
"API request failed":
- Verify your Zoho CRM permissions
- Check that the API domain is correct for your region
"Contact/Deal not found":
- Verify the search criteria
- Check that the record exists in your CRM

Environment Variable Issues

Missing environment variables:
- Ensure ZOHO_CLIENT_ID and ZOHO_CLIENT_SECRET are set in .env
- Check .env.example for the complete list
Invalid credentials:
- Verify your ZOHO_CLIENT_ID and ZOHO_CLIENT_SECRET
- Ensure they match your Zoho Developer Console app
Wrong redirect URI:
- Ensure ZOHO_REDIRECT_URI matches your Zoho app configuration
- Default should be http://localhost:8080/callback
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.

Zoho CRM MCP Server

Zoho CRM MCP Server

Features

Prerequisites

Installation

Option 1: Install from PyPI (Recommended)

Option 2: Install from Source

Setup

Step 1: Create Zoho Developer App

Step 2: Configure Environment Variables

Authentication Setup

Step 1: Generate Tokens

Step 2: Add Tokens to .env File

Running the MCP Server

Available MCP Tools

1. get_contact_by_email_tool

2. create_contact_tool

3. get_deal_by_name_tool

4. create_deal_tool

5. update_contact_tool

6. list_open_deals_tool

7. get_user_info_tool

Usage with MCP Clients

Claude Desktop

Other MCP Clients

Error Handling

Security Considerations

Current Implementation (Development)

Production Recommendations

Extending the Server

Troubleshooting

Common Issues

Environment Variable Issues

Debug Mode

API Rate Limits

Support

License

Zoho CRM MCP Server

Features

Prerequisites

Installation

Option 1: Install from PyPI (Recommended)

Option 2: Install from Source

Setup

Step 1: Create Zoho Developer App

Step 2: Configure Environment Variables

Authentication Setup

Step 1: Generate Tokens

Step 2: Add Tokens to .env File

Running the MCP Server

Available MCP Tools

1. get_contact_by_email_tool

2. create_contact_tool

3. get_deal_by_name_tool

4. create_deal_tool

5. update_contact_tool

6. list_open_deals_tool

7. get_user_info_tool

Usage with MCP Clients

Claude Desktop

Other MCP Clients

Error Handling

Security Considerations

Current Implementation (Development)

Production Recommendations

Extending the Server

Troubleshooting

Common Issues

Environment Variable Issues

Debug Mode

API Rate Limits

Support

License

1. `get_contact_by_email_tool`

2. `create_contact_tool`

3. `get_deal_by_name_tool`

4. `create_deal_tool`

5. `update_contact_tool`

6. `list_open_deals_tool`

7. `get_user_info_tool`

1. `get_contact_by_email_tool`

2. `create_contact_tool`

3. `get_deal_by_name_tool`

4. `create_deal_tool`

5. `update_contact_tool`

6. `list_open_deals_tool`

7. `get_user_info_tool`