Zoho CRM MCP Server

<!- - mcp-name: io.github.asklokesh/zoho-crm-mcp-server - ->

Zoho Crm Mcp Server

A Model Context Protocol (MCP) server for integrating Zoho CRM with GenAI applications.

# Overview

This MCP server provides seamless integration with Zoho CRM, enabling AI assistants and applications to interact with your CRM data through a standardized interface.

# Features

• 🔐 OAuth 2.0 Authentication - Secure authentication with automatic token refresh
• 📊 Comprehensive CRM Operations - Full support for Leads, Contacts, Deals, and more
• ⚡ Rate Limiting - Built-in rate limiting to respect API quotas
• 🔄 Automatic Retry Logic - Intelligent retry mechanism with exponential backoff
• 🛡️ Error Handling - Robust error handling and logging
• 🎯 MCP Protocol Compliance - Full compliance with Model Context Protocol specification
• 🚀 Async Support - Asynchronous operations for better performance

# Available Tools

The server exposes the following MCP tools:

1. get_leads - Retrieve leads from Zoho CRM with pagination
2. create_lead - Create new leads in Zoho CRM
3. get_contacts - Fetch contacts with pagination support
4. get_deals - Get deals from Zoho CRM
5. search_records - Search across any module with custom criteria

# Installation

# # From PyPI (when published)

pip install zoho-crm-mcp-server

# # From Source

git clone https://github.com/asklokesh/zoho-crm-mcp-server.git
cd zoho-crm-mcp-server
pip install -e .

# # Development Installation

pip install -e ".[dev]"

# Configuration

# # 1. Set Up Zoho OAuth Credentials

1. Go to Zoho API Console
2. Create a new Self Client application
3. Note your Client ID and Client Secret
4. Generate a refresh token with required scopes:
   • ZohoCRM.modules.ALL
   • ZohoCRM.settings.ALL

# # 2. Create Environment Configuration

Copy the example configuration:

cp .env.example .env

Edit .env with your credentials:

ZOHO_CLIENT_ID=your_client_id_here
ZOHO_CLIENT_SECRET=your_client_secret_here
ZOHO_REFRESH_TOKEN=your_refresh_token_here

#  Optional configurations
ZOHO_API_DOMAIN=https://www.zohoapis.com
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_PERIOD=60
MAX_RETRIES=3
LOG_LEVEL=INFO

# Usage

# # As a Standalone Server

zoho-crm-mcp

# # In Python Code

from zoho_crm_mcp import ZohoCRMMCPServer
import asyncio

async def main():
    server = ZohoCRMMCPServer()
    await server.run()

if __name__ == "__main__":
    asyncio.run(main())

# # Using the Zoho CRM Client

from zoho_crm_mcp import ZohoCRMClient, Config
import asyncio

async def main():
    config = Config()
    client = ZohoCRMClient(config)
    
    await client.initialize()
    
    #  Get leads
    leads = await client.get_leads(page=1, per_page=50)
    print(f"Found {len(leads['data'])} leads")
    
    #  Create a new lead
    new_lead = await client.create_lead({
        "Last_Name": "Doe",
        "First_Name": "John",
        "Email": "john.doe@example.com",
        "Company": "Acme Corp"
    })
    
    #  Search for records
    results = await client.search_records(
        "Leads",
        "(Email:equals:john.doe@example.com)"
    )
    
    await client.close()

if __name__ == "__main__":
    asyncio.run(main())

# Development

# # Running Tests

pytest tests/ -v - -cov=zoho_crm_mcp

# # Linting

ruff check src/ tests/
ruff format src/ tests/

# # Building

python -m build

# CI/CD

This project includes GitHub Actions workflows for:

• ✅ Automated testing across Python 3.8-3.12
• 🔍 Code quality checks with Ruff
• 📦 Package building and validation
• 📊 Code coverage reporting

# Architecture

zoho-crm-mcp-server/
├── src/zoho_crm_mcp/
│   ├── __init__.py       #  Package initialization
│   ├── server.py         #  MCP server implementation
│   ├── zoho_client.py    #  Zoho CRM API client
│   └── config.py         #  Configuration management
├── tests/                #  Comprehensive test suite
├── .github/workflows/    #  CI/CD pipelines
└── pyproject.toml        #  Project configuration

# Error Handling

The server includes comprehensive error handling:

• Token Expiry: Automatic token refresh when tokens expire
• Rate Limiting: Respects API rate limits with intelligent backoff
• Network Errors: Automatic retry with exponential backoff
• Validation Errors: Clear error messages for invalid configurations

# Logging

The server uses Python's built-in logging module. Configure log level via environment variable:

export LOG_LEVEL=DEBUG  #  Options: DEBUG, INFO, WARNING, ERROR, CRITICAL

# Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

# Troubleshooting

# # Common Issues

Issue: ModuleNotFoundError: No module named 'mcp'
Solution: Install the MCP SDK: pip install mcp

Issue: Token refresh fails
Solution: Verify your refresh token is valid and has the required scopes

Issue: Rate limit errors
Solution: Adjust RATE_LIMIT_REQUESTS and RATE_LIMIT_PERIOD in your .env file

# Requirements

• Python 3.8+
• requests >= 2.25.0
• mcp >= 1.0.0
• python-dotenv >= 0.19.0

# License

MIT License - see LICENSE file for details

# Support

For issues, questions, or contributions, please visit:

• GitHub Issues
• GitHub Discussions

# Acknowledgments

• Model Context Protocol - MCP specification
• Zoho CRM API - API documentation
• All contributors who help improve this project

Made with ❤️ for the MCP community