Zoho CRM MCP Server (FastAPI + FastMCP)

A production-grade Model Context Protocol (MCP) server built with FastAPI + FastMCP that gives Claude and other AI clients complete, authenticated access to the Zoho CRM REST API v8 — from reading records to designing modules and authoring workflow automation.

211 MCP tools covering records, COQL, schema design, workflow rules and their actions, webhooks, bulk/mass operations, tags, notes, email, security settings, and bulk import/export — plus a dashboard and report engine, function authoring and attachment to workflow rules, org hierarchy tools, and teamspaces — and a generic zoho_api_request escape hatch for anything Zoho exposes that has no dedicated tool.

🌟 Key Features

• FastAPI Web Framework: High-performance, production-ready ASGI app powered by Uvicorn.

• Dual Transport: Runs as a Streamable HTTP MCP server (for remote/cloud hosting) and as a STDIO MCP server (for local Claude Desktop).

• Full OAuth 2.0 Lifecycle: Automatic code exchange, browser redirect handler (/auth/callback), encrypted token storage, and a background loop that keeps the token fresh while the server runs.

• Chat-Configurable Credentials: Supply a Zoho Client ID/Secret from chat (set_zoho_credentials, or inline on get_auth_url/exchange_auth_code) instead of .env — useful for switching Zoho accounts without restarting.

• Dashboard Report Home Page: / serves a live dashboard — record counts per module, workflow and function inventory, org chart, teamspaces, pinned reports, and the activity feed — all backed by GET /api/dashboard/summary. Panels load concurrently and fail independently, so one missing OAuth scope never blanks the page.

• Report Engine: Save report definitions (list, count, summary with count/sum/avg/min/max and group-by) that compile to COQL and run against live CRM data. Pin one to the dashboard, re-run it on demand, or export it to CSV. Zoho has no Reports API, so this is the working substitute.

• Function Authoring (v8 Functions API): Create, read, update, publish, and delete Deluge/Java/NodeJS/Python functions, and download their source.

• Functions Attached to Workflows: functions is a first-class workflow action type, so a function can be wired into a rule as an instant or scheduled action — and detached again — without touching the Zoho UI.

• Org Hierarchy: Role and user-reporting trees assembled from Zoho's flat lists, with an ASCII org chart, subordinate/manager lookups, and the writes that reparent a role or reassign a manager.

• Teamspaces: Group modules and people into named teamspaces, optionally projected onto a real CRM user group so the same roster drives sharing and assignment in Zoho.

• Complete Automation Authoring: Build workflow rules end to end — create field-update, email-notification, task, and webhook actions, then wire them into a rule with triggers and criteria.

• Schema Design: Create custom modules (with the profiles Zoho mandates), fields, global picklists, layouts, and sales pipelines.

• Scoped Session Mode: ID-based safety filter (activate_scope) restricting operations to specific record IDs.

• Human-In-The-Loop Approvals: Destructive actions queue a pending request instead of executing. Toggle with ZOHO_REQUIRE_APPROVAL.

• Structured Activity Logging: Every auth event, API call, and approval decision logged as JSON, retrievable via get_logs() / GET /logs.

• Encrypted Token Storage: OAuth tokens encrypted at rest (Fernet/AES), never plaintext.

• Resilient Network Client: Pooled httpx client with automatic 401 refresh-and-retry, clamped 429 backoff, exponential 5xx retry, an outbound rate limiter, and partial-failure detection on Zoho's per-record responses.

• Multi-Account Isolation: Each Zoho client_id is an isolated tenant - its own tokens, scope, approval queue, reports, and teamspaces - resolved per MCP session or per REST header. Concurrent callers on different accounts cannot read or write each other's org.

• Automated Test Suite: 93 pytest tests covering the HTTP surface, tool registration, request-payload shapes, client guards, the COQL report compiler, hierarchy tree assembly, teamspace rostering, and function-to-workflow attachment.

Related MCP server: Zoho CRM MCP Server

📁 Repository Structure

zoho-crm-mcp/
├── server.py              # FastAPI app + all FastMCP tool definitions & REST endpoints
├── auth_manager.py        # OAuth 2.0 flow, scopes & token refresh
├── zoho_client.py         # Async HTTP client for Zoho CRM API v8 (193 methods)
├── models.py              # Pydantic state & validation models
├── token_store.py         # Encrypted (Fernet) token persistence
├── approval_manager.py    # HITL approval queue for high-risk actions
├── activity_log.py        # Structured JSON activity logger
├── dashboard.py           # Dashboard aggregation (concurrent, per-panel errors)
├── report_store.py        # Report definitions + COQL compiler, runner & CSV export
├── hierarchy.py           # Role/user tree assembly and hierarchy mutations
├── teamspace_store.py     # Teamspace registry + CRM user-group projection
├── web_ui.py              # The dashboard home page (no CDN, no build step)
├── tenancy.py             # Per-account isolation: tenant registry, ContextVar, proxies
├── test_server.py         # pytest suite
├── requirements.txt       # Dependencies
├── .env.example           # Environment configuration template
├── pyproject.toml         # Package metadata
└── README.md

⚙️ Setup & Installation

1. Prerequisites

• Python 3.10+

• A Zoho CRM API Console app (Zoho API Console)

  • Client Type: Server-based Applications

  • Redirect URI: http://localhost:8000/auth/callback (or your deployment callback URL)

2. Environment Setup

cp .env.example .env

Minimum configuration:

ZOHO_CLIENT_ID=1000.xxxxxxx
ZOHO_CLIENT_SECRET=xxxxxxx
ZOHO_REDIRECT_URI=http://localhost:8000/auth/callback
ZOHO_DATA_CENTER=com
PORT=8000

See .env.example for every supported variable, including the approval gate, OAuth scope override, rate limit, and timeout settings.

Working with more than one Zoho account? ZOHO_CLIENT_ID/ZOHO_CLIENT_SECRET are optional. Leave them blank and ask Claude to call set_zoho_credentials(client_id, client_secret, redirect_uri?, data_center?), or pass client_id/client_secret directly to get_auth_url / exchange_auth_code. Switching client_id clears tokens saved for the previous account, avoiding Zoho's invalid_client error from reusing a refresh token issued to a different app.

3. Install Dependencies

pip install -r requirements.txt

🚀 Running & Deploying

Option A: Local FastAPI Web Server

python server.py

Or with Uvicorn directly:

uvicorn server:app --host 0.0.0.0 --port 8000

Once running:

• Web Dashboard: http://localhost:8000/

• Swagger Docs: http://localhost:8000/docs

• Health Check: http://localhost:8000/health

• MCP Endpoint: http://localhost:8000/mcp/

The MCP endpoint is served at the mount root, so the path is /mcp/ — not /mcp/mcp. Keep the trailing slash: /mcp answers with a 307 redirect, which not every MCP client follows correctly on a POST.

Option B: Local STDIO

python server.py --stdio

Option C: Cloud Deployment (Render, Railway, Docker, AWS, Heroku)

• Start Command: uvicorn server:app --host 0.0.0.0 --port $PORT

• Health Check Path: /health

• Environment Variables: set ZOHO_CLIENT_ID, ZOHO_CLIENT_SECRET, ZOHO_REDIRECT_URI, ZOHO_DATA_CENTER, and ZOHO_TOKEN_ENCRYPTION_KEY (so tokens survive restarts on ephemeral filesystems).

Live deployment

Staying authenticated on an ephemeral host. Render wipes the filesystem on every deploy and restart, taking ~/.zoho_crm_tokens.json with it — and the Fernet key at ~/.zoho_crm_mcp.key is regenerated on each boot, so even a surviving token file could not be decrypted. Set both of these in the host's environment and the server re-authenticates itself instead of asking for tokens again:

• ZOHO_REFRESH_TOKEN — picked up on cold boot, so a fresh access token is minted automatically. Refresh tokens do not expire unless revoked.

• ZOHO_TOKEN_ENCRYPTION_KEY — a stable Fernet key, so the cached access token survives too. Generate one with:

  python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Token refresh itself is automatic and needs no configuration: get_valid_access_token() renews anything expiring within 5 minutes, and a background loop re-checks every ZOHO_TOKEN_REFRESH_INTERVAL seconds (default 120).

🖥️ Claude Desktop Integration

Mode 1: HTTP / Remote MCP Connection

Local:

{
  "mcpServers": {
    "zoho-crm": {
      "url": "http://localhost:8000/mcp/"
    }
  }
}

Deployed:

{
  "mcpServers": {
    "zoho-crm": {
      "url": "https://zoho-crm-mcp-07t7.onrender.com/mcp/"
    }
  }
}

The server has no MCP-level authentication, so leave any "OAuth Client ID" field in the connector settings blank. The Zoho OAuth inside the server authenticates it to Zoho; it does not gate the MCP endpoint. Pointing a client at the wrong path (/mcp/mcp) returns 404, which some clients report as a misleading sign-in or registration failure rather than as a bad URL.

Mode 2: Local STDIO Connection

{
  "mcpServers": {
    "zoho-crm": {
      "command": "python",
      "args": ["C:/Users/Lenovo/Desktop/zoho MCP/server.py", "--stdio"],
      "env": {
        "ZOHO_CLIENT_ID": "1000.YOUR_CLIENT_ID",
        "ZOHO_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "ZOHO_REDIRECT_URI": "http://localhost:8000/auth/callback",
        "ZOHO_DATA_CENTER": "com"
      }
    }
  }
}

🔑 First-Run OAuth Flow

1. Start the server: python server.py

2. Open http://localhost:8000/auth/url, or ask Claude to run get_auth_url().

3. Open the returned URL, sign in to Zoho CRM, click Accept.

4. Zoho redirects to /auth/callback?code=...; the server exchanges the code and saves encrypted tokens to ~/.zoho_crm_tokens.json.

🧩 Building Automation: The Workflow Recipe

Zoho models a workflow rule as a trigger plus conditions, where each condition points at pre-created action objects. Build them in that order:

1. get_workflow_configurations(module="Leads")
   -> see which triggers, comparators, and action types this org supports

2. create_field_update_action(
       name="Mark as Hot", module="Leads",
       field_api_name="Rating", value="Hot")
   -> returns the action id

3. create_workflow(
       name="Hot Lead Router",
       module="Leads",
       execute_when={"type": "create_or_edit"},
       conditions=[{
           "sequence_number": 1,
           "criteria_details": {"criteria": {"group_operator": "and", "group": [
               {"comparator": "equal",
                "field": {"api_name": "Lead_Source"},
                "value": "Web Form"}]}},
           "instant_actions": {"actions": [
               {"id": "<action id from step 2>", "type": "field_updates"}]}}])

4. activate_workflow(workflow_id="...")

The same pattern applies with create_email_notification_action, create_automation_task, and create_webhook as the action source.

📊 Dashboard & Report Home Page

GET / is a live dashboard, not a status card. It shows record counts per module, the workflow and function inventory (broken down by runtime and category), the org chart, teamspaces, every pinned report, and the recent activity feed — with an in-page report runner for ad-hoc queries.

Panels are fetched concurrently and each carries its own error, so a missing OAuth scope costs you one panel rather than the whole page. The same payload is available as JSON:

curl localhost:8000/api/dashboard/summary
curl "localhost:8000/api/dashboard/summary?modules=Deals,Leads&include_hierarchy=false"

From an MCP client:

get_dashboard_summary()                       # everything
get_module_record_counts(["Deals", "Leads"])   # just the counts

Reports

A report is a definition stored on this server that compiles to COQL and runs against live CRM data. Three shapes:

# 1. list — rows of fields
create_report(name="Big open deals", module="Deals", type="list",
              fields=["Deal_Name", "Stage", "Amount"],
              criteria="(Amount > 50000) and (Stage != 'Closed Won')",
              sort_by="Amount", sort_order="desc")

# 2. count — how many match
create_report(name="Web leads", module="Leads", type="count",
              criteria="(Lead_Source = 'Web Form')")

# 3. summary — aggregate, grouped; pinned to the dashboard home page
create_report(name="Pipeline by stage", module="Deals", type="summary",
              group_by=["Stage"],
              aggregates=[{"function": "sum", "field": "Amount", "alias": "pipeline"}],
              pinned=True)

run_report("Pipeline by stage")                    # by name or id
run_adhoc_report(module="Deals", type="count")     # iterate without saving
export_report("Pipeline by stage", save_to="./pipeline.csv")

Aggregates take count, sum, avg, min, and max; alias is the column name you get back. criteria is a COQL where clause, and omitting it matches every record. Rows cap at 2000 per report — use bulk_read_create_job for a full export.

create_dashboard_widget(...) is the same thing pinned in one step.

⚡ Functions, and Attaching Them to Workflows

v8 exposes a real Functions API, so functions are authored over the wire. Deluge source goes inline; Java, NodeJS, and Python ship as a ZIP and then need publishing.

get_function_runtimes()     # what this org allows, and what's deprecated
get_function_categories()   # 'Automation' is the workflow-callable one

create_function(
    name="Flag big deal",
    api_name="flag_big_deal",
    category="Automation",
    runtime="Deluge 1.0",
    code='''void automation.flag_big_deal(Map deal)
{
    // Deluge body
}''')

get_function_code("flag_big_deal")               # read it back
update_function("flag_big_deal", code="...")     # Deluge auto-publishes
publish_function("nightly_sync")                 # Java/NodeJS/Python drafts

api_name, runtime, and category are immutable in Zoho — to change any of them, create a new function.

functions is a first-class workflow action type, so a function can be wired straight into a rule:

# instant: runs the moment the rule fires
attach_function_to_workflow(workflow_id="...", function="flag_big_deal", module="Deals")

# scheduled: runs two days later
attach_function_to_workflow(workflow_id="...", function="flag_big_deal", module="Deals",
                            scheduled_after={"period": "days", "unit": 2})

list_workflow_actions(workflow_id="...", module="Deals")
detach_function_from_workflow(workflow_id="...", function="flag_big_deal", module="Deals")

A rule's actions hang off its conditions, so attaching one is read-modify-write on the target condition — existing actions on that condition are preserved. condition_sequence picks which condition (default 1). attach_action_to_workflow does the same for the other action types: pass action_id for an existing field update, email notification, task, or webhook, or details for an inline action like add_tags or create_record. Check get_workflow_configurations(module=...) first — a trigger only accepts certain actions.

🏢 Hierarchy & Teamspaces

Hierarchy

Zoho returns roles and users as flat lists with reporting_to pointers and no tree endpoint, so these tools assemble one:

get_hierarchy_preference()      # Role_Hierarchy or Reporting_Hierarchy (read-only in Zoho)
get_role_hierarchy()            # nested tree + an ASCII org chart + depth
get_user_hierarchy()            # same, from each user's reporting_to
get_subordinates("4876...001", of="user", deep=True)   # + the managers above them

Both trees come with an ascii org chart, which is what an AI client can actually read back:

CEO
├── VP Sales
│   ├── Manager EU
│   │   ├── AE Berlin
│   │   └── AE Paris
│   └── Manager US
└── VP Marketing

A role whose parent is outside your permission scope still appears, listed under orphans rather than silently dropped. The mutations are real Zoho writes:

create_role_under(name="Manager EU", parent_role_id="...")
set_role_parent(role_id="...", parent_role_id="...")   # moves the whole subtree
set_user_manager(user_id="...", manager_user_id="...")  # omit to clear
assign_user_role(user_id="...", role_id="...")

Teamspaces

Teamspaces group modules and people. Zoho's REST API has no teamspaces endpoint, so the roster lives on this server — and can be projected onto a real CRM user group, which is Zoho's own way to name a set of people for sharing and assignment:

create_teamspace(
    name="EMEA Sales",
    modules=["Deals", "Contacts"],
    members=["4876...001", {"user_id": "4876...002", "role": "viewer"}],
    lead_user_id="4876...001",
    create_crm_user_group=True)     # also creates the Zoho user group

add_teamspace_members("EMEA Sales", [{"user_id": "...", "role": "member"}])
set_teamspace_modules("EMEA Sales", add=["Tasks"], remove=["Contacts"])
sync_teamspace_to_crm("EMEA Sales")   # push the roster onto the linked group
get_user_teamspaces("4876...001")

Member roles are lead, member, or viewer. If the CRM user group can't be created (a duplicate name, say), the teamspace is still kept and the response says the CRM-side binding failed — the registry is the source of truth, the group is its projection.

The underlying Zoho user groups are also directly addressable: get_user_groups, create_user_group, update_user_group, delete_user_group, get_user_group_associations.

🌐 REST Surface

Beyond the MCP endpoint, the dashboard's data is plain JSON:

Every endpoint accepts an X-Zoho-Client-Id header to select which account it acts for.

👥 Multi-Account Isolation (Tenancy)

This server is safe to share between many Zoho accounts and many AI clients at once. Each Zoho client_id is a tenant with its own tokens, scope, approval queue, reports, and teamspaces. Concurrent callers using different credentials cannot read or write each other's org.

How a caller picks its account

MCP clients — call set_zoho_credentials once; that session is bound to the account for its lifetime, and every later tool call routes there automatically:

set_zoho_credentials(client_id="1000.AAAA", client_secret="...")
get_tenant_info()      # confirm which account you are pointed at
create_record(...)     # goes to 1000.AAAA, whatever other sessions are doing

REST callers — send the account's client_id as a header:

curl localhost:8000/api/reports -H 'X-Zoho-Client-Id: 1000.AAAA'
curl localhost:8000/tenants     # resident accounts, credentials masked

Resolution order, first match wins: an explicit binding on the current task → the calling MCP session's binding → the X-Zoho-Client-Id header → the .env account. A deployment that never calls set_zoho_credentials behaves exactly as a single-account server, on the same file paths as before.

What is isolated, and why each one matters

How the isolation works

The current tenant lives in a contextvars.ContextVar. ContextVars are copied per asyncio task, so two interleaved requests each see their own value — isolation by construction rather than by locking. The module-level names (zoho_client, auth_manager, …) are thin proxies that resolve the calling task's tenant on every attribute access, which is why all 211 tool bodies are unchanged.

OAuth needed one extra step: a browser callback carries no session, so get_auth_url puts the tenant key in the OAuth state parameter and /auth/callback reads it back to store the tokens against the right account.

Operating notes

• Tenant state lives under ZOHO_STATE_DIR (default ~/.zoho_crm_mcp/tenants/<hash>/), one directory per account, named by a hash of the client_id rather than the client_id itself. The .env account keeps the original home-directory paths.

• Residency is capped by ZOHO_MAX_TENANTS (default 250); idle tenants past the cap have their connection pools closed by the background loop. Tenants still bound to a live session are never evicted.

• Token refresh runs per tenant inside that tenant's context, so a refresh can never write one account's token into another's store.

• get_tenant_info() reports which account a session resolved to and how. Worth calling before anything destructive.

🎯 Scoped Session Mode (Safety Filter)

Restrict every operation to specific record IDs:

• Activate: activate_scope(module="Deals", record_ids=["4153...001", "4153...002"])

• REST: POST /scope/activate with {"module": "Leads", "record_ids": ["123", "456"]}

• Deactivate: deactivate_scope() or POST /scope/deactivate

While active, reads on that module are filtered to those IDs, and writes to any other ID are refused with OUT_OF_SCOPE.

✅ Human-In-The-Loop (HITL) Approvals

By default, destructive actions queue a pending request and return a request_id instead of running:

delete_record, bulk_update_records, bulk_delete_records, mass_update_records, mass_delete_records, change_owner, mass_change_owner, merge_records, delete_workflow, delete_workflows, execute_blueprint, update_layout, activate_layout, delete_layout, delete_field, delete_user, delete_tag, bulk_write_create_job.

• Review: list_pending_approvals() or GET /approvals

• Approve & execute: approve_action(request_id="...") or POST /approvals/{id}/approve

• Reject & discard: reject_action(request_id="...") or POST /approvals/{id}/reject

• Disable the gate entirely: set ZOHO_REQUIRE_APPROVAL=false so these tools execute immediately.

Every request, approval, and rejection is written to the activity log.

📜 Activity Logging

Auth events, outbound Zoho API calls, function executions, and approval decisions are recorded as {timestamp, action, status, details} entries — held in memory and appended to ~/.zoho_crm_mcp_activity.log.jsonl.

• Retrieve: get_logs(limit=50, action=None, status=None) or GET /logs

🔐 Token Security

• Tokens are encrypted at rest (Fernet/AES) in ~/.zoho_crm_tokens.json.

• The key is auto-generated into ~/.zoho_crm_mcp.key on first run (user-only permissions on POSIX), or set explicitly via ZOHO_TOKEN_ENCRYPTION_KEY for a stable key across container restarts.

• Tokens are tagged with the client_id that issued them and discarded on mismatch, which prevents Zoho's invalid_client error after switching accounts.

• Outbound calls are self-throttled (ZOHO_RATE_LIMIT_PER_SEC, default 10/sec) on top of 429/5xx backoff.

🧪 Testing

pytest -v

Covers the HTTP surface (/health, /, /auth/*, /scope/*, /approvals/*, /logs, /api/*), registration of all 211 MCP tools plus a regression guard that the original 167 are still there, the exact request payloads sent for workflows/modules/notes/calls/webhooks/merges/locks and the Functions API's multipart body, the COQL compiler (including its limit clamp and the mandatory WHERE clause), aggregate-alias relabelling, hierarchy tree assembly (orphans and parent cycles included), per-panel dashboard error isolation, teamspace membership rules, function-to-workflow attach/detach across instant and scheduled actions, and multi-account isolation - including a concurrency test that drives overlapping interleaved calls from many accounts and asserts every request carried its own credentials (the old shared-singleton design failed that on 96 of 100 calls).

Tests run entirely offline — no Zoho credentials required.

🛠️ MCP Tool Reference

† Approval-gated by default. Set ZOHO_REQUIRE_APPROVAL=false to execute immediately.

* Zoho CRM's public REST API has no endpoint for this operation — blueprint authoring is UI-only. These tools return a clear NOT_SUPPORTED_BY_ZOHO_API message naming a working alternative, rather than failing against a URL that doesn't exist. (Driving records through an existing blueprint does work: get_blueprints / execute_blueprint.)

‡ Zoho exposes no Reports, Dashboards, Teamspaces, or hierarchy-tree endpoint, so these features are implemented on this server against real CRM data:

• Reports are definitions stored here that compile to COQL (or to /actions/count) and execute live. get_reports(module=...) also returns that module's Custom Views, which are the closest thing Zoho itself exposes.

• The dashboard is computed from live figures — module counts, workflow and function inventory, hierarchy, teamspaces, pinned reports.

• Hierarchy tools assemble a tree from /settings/roles and /users (Zoho returns flat lists with reporting_to pointers); the mutations are real Zoho writes. hierarchy_preferences is read-only in Zoho's API.

• Teamspaces are stored here and can be projected onto a real CRM user group (/settings/user_groups) so the roster is usable inside Zoho.

Definitions persist as JSON beside the token store (~/.zoho_crm_mcp_reports.json, ~/.zoho_crm_mcp_teamspaces.json). On an ephemeral host, mount a disk or accept that they reset on redeploy — the CRM data they read is never affected.

🧭 Reaching Anything Not Listed

Zoho's API is larger than any hand-written wrapper. zoho_api_request covers the rest with the same auth, throttling, and retry handling:

zoho_api_request(
    method="GET",
    endpoint="settings/territories")

zoho_api_request(
    method="POST",
    endpoint="settings/automation/scoring_rules",
    body={"scoring_rules": [{...}]})

zoho_api_request(
    method="GET",
    endpoint="read/1234567890",
    api_root="bulk")

api_root selects the URL base: crm → {domain}/crm/v8 (default), bulk → {domain}/crm/bulk/v8, root → {domain}.