Zoho Crm

MCP server and optional FastAPI wrapper for live Zoho CRM data access.

This project does not sync CRM data into a database or knowledge graph. Zoho remains the source of truth. The server discovers your Zoho modules, fields, and related lists, then exposes generic tools that can query standard modules, custom modules, subforms, and linking modules through Zoho's API names.

What This Provides

• MCP server for agent/client integrations.
• FastAPI /docs UI for manual testing.
• Single plain-text /query endpoint for simple natural-language CRM lookups.
• Zoho metadata discovery for modules, fields, and related lists.
• Generic module-aware tools instead of hardcoded Contacts/Deals-only logic.

Repository Safety

These files are intentionally ignored and should not be committed:

• .env
• zoho_metadata.json
• knowledge_graph.db
• __pycache__/

zoho_metadata.json contains schema metadata from your Zoho org. It does not contain synced CRM records, but it can still reveal internal module and field names, so keep it local.

Setup

Create a local .env:

ZOHO_CLIENT_ID=...
ZOHO_CLIENT_SECRET=...
ZOHO_REFRESH_TOKEN=...
OPENAI_API_KEY=...

Optional, depending on your Zoho data center:

ZOHO_ACCOUNTS_URL=https://accounts.zoho.in
ZOHO_API_DOMAIN=https://www.zohoapis.in
OPENAI_MODEL=gpt-4o-mini

Install dependencies:

python3 -m pip install -r requirements.txt

Discover modules, fields, and related lists:

python3 discover_zoho.py

This creates local zoho_metadata.json.

Run MCP Server

python3 zoho_mcp_server.py

Example MCP client config:

{
  "mcpServers": {
    "zoho-crm": {
      "command": "python3",
      "args": [
        "/absolute/path/to/zoho_mcp_server.py"
      ]
    }
  }
}

MCP Tools

• refresh_metadata
• list_modules
• get_module_fields
• get_related_lists
• search_records
• get_records
• get_record
• get_related_records
• query_coql

Note: query_coql requires a Zoho refresh token with the correct COQL scope. If the token does not include that scope, normal record tools still work.

Optional Swagger UI

Start FastAPI:

uvicorn api:app --host 127.0.0.1 --port 8000

Open:

http://127.0.0.1:8000/docs

Useful endpoints:

• POST /query
• GET /query
• GET /modules
• GET /modules/{module}/fields
• GET /modules/{module}/related-lists
• GET /records/{module}
• POST /records
• GET /records/{module}/search
• POST /records/search
• GET /record/{module}/{record_id}
• POST /related-records
• POST /coql

Plain-Text Query Endpoint

POST /query takes a raw text body and returns plain text. By default it uses the LLM agent wrapper above the MCP tools.

Example body:

latest contacts

Other examples:

find contacts matching Amit
top 5 revenue accounts
deals closing this month
what fields are in Accounts
what related lists are in Contacts
latest invoices

The /query endpoint is intentionally pragmatic. It handles common CRM lookups and a few analytical shortcuts. For deep analytics, add COQL scope or later add a materialized analytical store such as Postgres or DuckDB.

Use the deterministic rule-based fallback if needed:

POST /query?mode=rules

Use the LLM tool-calling agent:

POST /query?mode=agent