🚀 Zoho CRM MCP Server & Antigravity Skill

<p align="center"> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-Model%20Context%20Protocol-blue.svg?style=for-the-badge" alt="MCP"></a> <a href="https://antigravity.google"><img src="https://img.shields.io/badge/Antigravity-Ready-purple.svg?style=for-the-badge" alt="Antigravity"></a> <a href="https://www.zoho.com/crm/"><img src="https://img.shields.io/badge/Zoho%20CRM-API%20v6-red.svg?style=for-the-badge" alt="Zoho CRM"></a> <a href="https://python.org"><img src="https://img.shields.io/badge/Python-3.10%2B-green.svg?style=for-the-badge" alt="Python"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge" alt="License"></a> </p>

---

🌟 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.

---

🏗️ 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

Tool	Category	Description
zoho_coql_query	🔍 Query	SQL-like query engine (COQL) for filtering and sorting CRM data.
zoho_list_records	📋 Modules	List records from any standard or custom CRM module.
zoho_get_record	📄 Records	Retrieve full record details by module and unique ID.
zoho_search_records	🔎 Search	Search by criteria, keyword, email, or phone.
zoho_insert_records	➕ Create	Create single or batch records with workflow triggers.
zoho_update_records	✏️ Update	Update existing records by ID.
zoho_upsert_records	🔄 Upsert	Deduplicate automatically based on matching fields (e.g. Email).
zoho_delete_records	🗑️ Delete	Move record(s) to trash bin.
zoho_change_deal_stage	💼 Sales	Change deal stage, update amount, closing date, and next step.
zoho_get_module_meta	⚙️ Schema	Inspect field API names, data types, and picklist choices.
zoho_list_modules	🗺️ Setup	Discover all accessible modules in the Zoho organization.

---

🚀 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 (Claude Code, Claude Desktop, Antigravity CLI/IDE, Cursor) and register zoho-crm in each.
4. Copy the Antigravity Skill (skills/zoho-crm) into your local skills directory.

4. Verify Connection

zoho-mcp status
zoho-mcp doctor

---

🤖 Antigravity & IDE Integration

zoho-mcp setup writes these configs automatically. See Setup per AI host for every supported host and its exact config path on macOS, Windows, and Linux.

On Windows, JSON treats \ as an escape character, so either double every backslash or use forward slashes:

"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.