# Zoho CRM MCP

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

```bash
ZOHO_CLIENT_ID=...
ZOHO_CLIENT_SECRET=...
ZOHO_REFRESH_TOKEN=...
OPENAI_API_KEY=...
```

Optional, depending on your Zoho data center:

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

Install dependencies:

```bash
python3 -m pip install -r requirements.txt
```

Discover modules, fields, and related lists:

```bash
python3 discover_zoho.py
```

This creates local `zoho_metadata.json`.

## Run MCP Server

```bash
python3 zoho_mcp_server.py
```

Example MCP client config:

```json
{
  "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:

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

Open:

```text
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:

```text
latest contacts
```

Other examples:

```text
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:

```text
POST /query?mode=rules
```

Use the LLM tool-calling agent:

```text
POST /query?mode=agent
```