🚀 Zoho CRM MCP Server & Antigravity Skill

🌟 Overview

zoho-crm-mcp is an enterprise-grade Model Context Protocol (MCP) server and Antigravity Skill designed specifically for Zoho CRM. Inspired by the architecture of googleads/google-ads-mcp, it bridges AI models (Google Antigravity, Claude, ChatGPT, Cursor) with Zoho CRM's API v6.

🎤 Presented at the Zoho User & Developer Conference!
This open-source repository was built to give developers and sales engineering teams a turnkey solution for AI-driven CRM automation. Check out our Event Handout & Quick Sheet.

Related MCP server: AI-Assisted CRM MCP Server

🏗️ Architecture

flowchart TD
    subgraph Client["🤖 AI Host Environment"]
        Agent["Antigravity / Claude Agent"]
        Skill["Antigravity Skill\n(skills/zoho-crm/SKILL.md)"]
    end

    subgraph MCP["⚙️ Model Context Protocol"]
        Server["zoho-crm-mcp Server\n(FastMCP / Stdio)"]
        AuthCLI["Auth CLI Wizard\n(zoho-mcp auth)"]
    end

    subgraph Zoho["☁️ Zoho Cloud (Multi-DC)"]
        OAuth["Zoho OAuth 2.0 Server"]
        CRM["Zoho CRM REST API v6\n(Leads, Deals, COQL Engine)"]
    end

    Agent <-->|Stdio Protocol| Server
    Skill --> Agent
    Server <-->|Auto-Refreshed Tokens| CRM
    AuthCLI <-->|Grant Code Exchange| OAuth

✨ Features & Tools Matrix

🚀 Quick Start (5 Minutes)

1. Installation

macOS / Linux

git clone https://github.com/henriquecaner/zoho-crm-mcp.git
cd zoho-crm-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install .

Windows (PowerShell)

git clone https://github.com/henriquecaner/zoho-crm-mcp.git
cd zoho-crm-mcp
py -m venv .venv
.venv\Scripts\Activate.ps1
pip install .

Contributors: pip install -e . works normally on Windows and Linux. On macOS with Python 3.14 only, Hatchling marks its editable .pth file as hidden and Python 3.14 skips hidden .pth files, so the package will not import. There, use the plain pip install . shown above, or clear the flag with chflags nohidden .venv/lib/python3.*/site-packages/_editable_impl_*.pth.

2. Configure Zoho API Credentials

1. Open the Zoho API Console.

2. Click Add Client ➔ Server-based Applications.

3. Set Authorized Redirect URI: http://localhost:8989/callback

4. Copy your Client ID and Client Secret.

3. One-Command Interactive Setup Wizard

zoho-mcp setup

The automatic wizard will:

1. Prompt for your Client ID, Client Secret, and Data Center region.

2. Launch the OAuth browser flow to generate your Refresh Token.

3. Auto-detect your AI tools (Antigravity CLI/IDE, Claude Desktop, Cursor) and register zoho-crm into your mcp.json.

4. Copy the Antigravity Skill (skills/zoho-crm) into your local skills directory.

4. Verify Connection

zoho-mcp status

🤖 Antigravity & IDE Integration

Add zoho-crm-mcp to your Antigravity MCP configuration (~/.gemini/config/mcp.json or .antigravity/mcp.json):

{
  "mcpServers": {
    "zoho-crm": {
      "command": "/absolute/path/to/zoho-crm-mcp/.venv/bin/zoho-mcp",
      "args": ["server"],
      "env": {
        "ZOHO_CLIENT_ID": "YOUR_CLIENT_ID",
        "ZOHO_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "ZOHO_REFRESH_TOKEN": "YOUR_REFRESH_TOKEN",
        "ZOHO_ACCOUNTS_URL": "https://accounts.zoho.com",
        "ZOHO_API_DOMAIN": "https://www.zohoapis.com"
      }
    }
  }
}

On Windows, the executable lives in .venv\Scripts\ and ends in .exe. JSON treats \ as an escape character, so either double every backslash or use forward slashes — both of these work, a single-backslash path does not:

"command": "C:\\Users\\you\\zoho-crm-mcp\\.venv\\Scripts\\zoho-mcp.exe"
"command": "C:/Users/you/zoho-crm-mcp/.venv/Scripts/zoho-mcp.exe"

📚 Documentation & Resources

• 🎤 Event Presentation Handout

• 📖 GitHub Wiki

• 🧠 Antigravity Skill Guide

🤝 Contributing

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

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.