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.

• Chat-Configurable Credentials: Supply a Zoho Client ID/Secret directly from chat (set_zoho_credentials, or inline on get_auth_url/exchange_auth_code) instead of .env - useful when switching between different Zoho accounts/API console apps without restarting the server.

• 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.

Related MCP server: Zoho CRM MCP Server

📁 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

Working with more than one Zoho account? ZOHO_CLIENT_ID/ZOHO_CLIENT_SECRET are optional. You can leave them blank in .env and instead 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. This configures the running server for that session without restarting it or editing files. Switching to a different client_id automatically clears any tokens saved for the previous account, which avoids Zoho's invalid_client error caused by reusing a refresh token issued to a different API console app.

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