# 🚀 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`](https://github.com/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](docs/TALK_HANDOUT.md).

---

## 🏗️ Architecture

```mermaid
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**

```bash
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)**

```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](https://api-console.zoho.com/).
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

```bash
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

```bash
zoho-mcp status
zoho-mcp doctor
```

---

## 🤖 Antigravity & IDE Integration

`zoho-mcp setup` writes these configs automatically. See
[Setup per AI host](docs/SETUP_PER_HOST.md) 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:

```json
"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](docs/TALK_HANDOUT.md)
- 📖 [GitHub Wiki](docs/WIKI.md)
- 🧠 [Antigravity Skill Guide](skills/zoho-crm/SKILL.md)

---

## 🤝 Contributing

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

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.