Zoho Crm MCP Server

🚀 Zoho CRM MCP Server

A Model Context Protocol (MCP) server for integrating Zoho CRM with GenAI applications, providing a standardized interface for AI assistants and applications to interact with CRM data.

🚀 Quick Start

This MCP server offers seamless integration with Zoho CRM, allowing 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.

📦 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]"

💻 Usage Examples

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())

📚 Documentation

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.

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

🔧 Technical Details

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

📄 License

MIT License - see LICENSE file for details

🤝 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

📞 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