Zoho CRM MCP Server (FastAPI + FastMCP)

A production-grade Model Context Protocol (MCP) server built with FastAPI + FastMCP that provides Claude Desktop and AI clients with complete, authenticated access to the Zoho CRM REST API v8.

---

🌟 Key Features

• FastAPI Web Framework: High-performance, production-ready web application powered by Uvicorn and FastAPI.
• Dual Transport Support: Runs seamlessly both as a Web/HTTP/SSE MCP Server (for remote deployment & 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), token storage, and automatic token refresh.
• Scoped Session Mode: ID-based safety filter (activate_scope) that restricts operations exclusively to specific record IDs to prevent accidental modifications.
• Interactive OpenAPI Documentation: Built-in Swagger UI accessible at /docs.
• Resilient Network Client: Built with httpx featuring automatic 401 token refresh retry, HTTP 429 rate limit backoff, and exponential retry for 5xx errors.
• Automated Test Suite: Complete test suite using pytest and FastAPI TestClient.

---

📁 Repository Structure

zoho-crm-mcp/
├── server.py              # FastAPI application + FastMCP tool definitions & endpoints
├── auth_manager.py        # OAuth 2.0 flow & token refresh manager
├── zoho_client.py         # Async HTTP client wrapper for Zoho CRM API v8
├── models.py              # Pydantic state & validation models
├── token_store.py         # File-based JSON token persistence (~/.zoho_crm_tokens.json)
├── test_server.py         # Automated pytest test suite
├── requirements.txt       # Project dependencies
├── .env.example           # Environment configuration template
├── pyproject.toml         # Package metadata
└── README.md              # Server documentation

---

⚙️ Setup & Installation

1. Prerequisites

• Python 3.10+
• A Zoho CRM Developer Account / API Console App (Zoho API Console)
  • Client Type: Server-based Applications
  • Redirect URI: http://localhost:8000/auth/callback (or your production deployment callback URL)

2. Environment Setup

Copy .env.example to .env:

cp .env.example .env

Configure .env with your Zoho API application credentials:

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

3. Install Dependencies

Using pip:

pip install -r requirements.txt

---

🚀 Running & Deploying the Server

Option A: Local Development / FastAPI Web Server

To start the FastAPI web server with Uvicorn auto-reload:

python server.py

Or directly with Uvicorn:

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

Once running, access:

• Web Dashboard: http://localhost:8000/
• Interactive Swagger Docs: http://localhost:8000/docs
• Health Check: http://localhost:8000/health
• MCP HTTP/SSE Endpoint: http://localhost:8000/mcp/mcp

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

Deploy using standard ASGI entrypoint server:app:

• 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 in your hosting dashboard.

---

🧪 How to Test the Server

1. Run Automated Test Suite (pytest)

Execute all unit and integration tests using pytest:

pytest -v

This runs tests verifying:

• Health check endpoint (/health)
• Root landing page dashboard (/)
• OAuth URL generation (/auth/url)
• OAuth callback handler (/auth/callback)
• Scoped mode state lifecycle (/scope, /scope/activate, /scope/deactivate)
• Registration of all 30+ FastMCP tools.

2. Test via Interactive Swagger UI

1. Open http://localhost:8000/docs in your browser.
2. Test /health to verify server status.
3. Test /auth/url to receive your OAuth authorization URL.
4. Test /scope endpoints to manage scoped record access.

3. Test OAuth Login Flow in Browser

1. Start server: python server.py
2. Open http://localhost:8000/auth/url in browser or ask Claude to run get_auth_url().
3. Open the returned URL, sign in to Zoho CRM, and click Accept.
4. Zoho will redirect to http://localhost:8000/auth/callback?code=....
5. The FastAPI server will automatically exchange the code, save tokens to ~/.zoho_crm_tokens.json, and render a success confirmation page.

---

🖥️ Claude Desktop Integration

Mode 1: HTTP / Remote MCP Connection

In claude_desktop_config.json:

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

Mode 2: Local STDIO Connection

In claude_desktop_config.json:

{
  "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"
      }
    }
  }
}

---

🎯 Scoped Session Mode (Safety Filter)

Restrict operations exclusively to specific record IDs to prevent unintended modifications:

• Activate: activate_scope(module="Deals", record_ids=["415340000000123001", "415340000000123002"])
• REST Activation: POST http://localhost:8000/scope/activate with JSON {"module": "Leads", "record_ids": ["123", "456"]}
• Deactivate: deactivate_scope() or POST http://localhost:8000/scope/deactivate

---

🛠️ Complete MCP Tool Reference

Category	Tools Included
OAuth & Auth	get_auth_url, exchange_auth_code
Scoped Mode	activate_scope, deactivate_scope, get_scope_status
Record CRUD	create_record, get_record, update_record, delete_record, list_records, search_records, upsert_record
COQL Engine	execute_coql
Metadata & Discovery	get_modules, get_fields, get_layouts, get_related_lists, get_users, get_organizations
Settings API	create_module, update_module, create_field, update_field, delete_field, get_custom_views
Workflows	create_workflow, get_workflows, update_workflow, activate_workflow, deactivate_workflow, delete_workflow
Bulk Operations	bulk_create_records, bulk_update_records, bulk_delete_records
Attachments & Notes	upload_attachment, get_attachments, download_attachment, create_note, get_notes, create_call
Record Actions & Tags	convert_lead, add_tags, remove_tags, get_blueprints, execute_blueprint