zoho-recruit-mcp-server

An MCP (Model Context Protocol) server that bridges Claude and the Zoho Recruit ATS. It lets Claude search candidates, manage jobs and interviews, run recruitment analytics, send candidate email, and use AI-assist tools — all through natural language.

Claude  ⇄  Model Context Protocol  ⇄  this server  ⇄  Zoho Recruit API v2  ⇄  Recruitment data

Example prompts once connected:

• "Show me all candidates interviewed for the TPM role this week"

• "Find candidates with React.js experience"

• "Move candidate to the Technical Interview stage"

• "Create a new job opening for a Senior Backend Engineer"

• "Schedule an interview for candidate 12345 with alice@acme.com on 2026-07-01 at 14:30"

• "Generate a hiring funnel report for Q2"

• "Find candidates rejected in the last 30 days"

• "Send the interview invitation email to candidate 12345"

1. Architecture

zoho-recruit-mcp-server/
├── src/
│   ├── server.py              # FastMCP entrypoint, transport selection
│   ├── config.py              # pydantic settings + region/URL resolution
│   ├── services.py            # wires client + domain APIs together
│   ├── auth/
│   │   └── zoho_auth.py        # OAuth2 refresh-token -> access-token manager
│   ├── zoho/
│   │   ├── client.py           # async httpx client: retry, rate limit, 401 recovery
│   │   ├── common.py           # search-criteria builders, response helpers
│   │   ├── candidates.py       # Candidates module operations
│   │   ├── jobs.py             # Job_Openings module operations
│   │   ├── interviews.py       # Interviews module operations
│   │   ├── reports.py          # analytics (funnel, recruiter, source)
│   │   ├── email.py            # candidate email automation
│   │   └── ai_helpers.py       # resume parsing, match scoring, summaries
│   ├── tools/
│   │   ├── candidate_tools.py  # MCP tool registration (candidates)
│   │   ├── job_tools.py        # MCP tool registration (jobs)
│   │   ├── interview_tools.py  # MCP tool registration (interviews)
│   │   ├── analytics_tools.py  # MCP tool registration (analytics)
│   │   ├── email_tools.py      # MCP tool registration (email)
│   │   └── ai_tools.py         # MCP tool registration (AI assist)
│   ├── models/
│   │   ├── candidate.py        # pydantic input models + Zoho field mapping
│   │   └── job.py
│   └── utils/
│       ├── logger.py           # structured logging + secret/PII redaction
│       └── error_handler.py    # error taxonomy + MCP error formatting
├── tests/                      # pytest unit + integration tests
├── requirements.txt
├── pyproject.toml
├── Dockerfile
├── docker-compose.yml
├── claude_config.json
├── .env.example
└── README.md

Transports

• STDIO — for Claude Desktop (default).

• Streamable HTTP — for cloud deployment and the MCP Inspector (endpoint /mcp).

Related MCP server: Ashby MCP Server

2. Setup

Prerequisites

• Python 3.12+

• A Zoho Recruit account with API access

Install

git clone <your-repo-url> zoho-recruit-mcp-server
cd zoho-recruit-mcp-server

python3.12 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

pip install -r requirements.txt
cp .env.example .env                # then fill in your Zoho credentials

3. Zoho setup (OAuth)

1. Register a client at the Zoho API console: https://api-console.zoho.com/

   • Choose Server-based Applications.

   • Note the Client ID and Client Secret.

   • Set an authorized redirect URI (e.g. https://www.zoho.com/recruit or your own callback).

2. Pick scopes. A broad working scope is:

   ZohoRecruit.modules.ALL,ZohoRecruit.settings.ALL

   For least privilege you can narrow to specific module scopes (e.g. ZohoRecruit.modules.candidates.ALL).

3. Get an authorization code. In a browser (use the accounts host for your region, e.g. accounts.zoho.in for India):

   https://accounts.zoho.com/oauth/v2/auth?response_type=code
     &client_id=YOUR_CLIENT_ID
     &scope=ZohoRecruit.modules.ALL,ZohoRecruit.settings.ALL
     &redirect_uri=YOUR_REDIRECT_URI
     &access_type=offline
     &prompt=consent

   access_type=offline is required to receive a refresh token. Copy the code value from the redirect URL (it expires within minutes).

4. Exchange the code for a refresh token:

   curl -X POST "https://accounts.zoho.com/oauth/v2/token" \
     -d "grant_type=authorization_code" \
     -d "client_id=YOUR_CLIENT_ID" \
     -d "client_secret=YOUR_CLIENT_SECRET" \
     -d "redirect_uri=YOUR_REDIRECT_URI" \
     -d "code=PASTE_THE_CODE"

   Save the refresh_token from the response. This server uses only the refresh token at runtime; access tokens are fetched and rotated automatically.

5. Fill .env:

   ZOHO_CLIENT_ID=...
   ZOHO_CLIENT_SECRET=...
   ZOHO_REFRESH_TOKEN=...
   ZOHO_REGION=com        # com | eu | in | au | jp | ca

   The accounts and API base URLs are derived from ZOHO_REGION. Override with ZOHO_ACCOUNTS_URL / ZOHO_BASE_URL only for custom domains.

Region note: use the accounts host matching the DC where your Zoho account lives (.com, .eu, .in, .com.au, .jp, zohocloud.ca). Using the wrong region produces invalid_code / auth errors.

4. Connecting to Claude

Claude Desktop (STDIO)

Add the server to your Claude Desktop config (claude_desktop_config.json), using the absolute path to your checkout:

{
  "mcpServers": {
    "zoho-recruit": {
      "command": "python",
      "args": ["-m", "src.server"],
      "env": {
        "ZOHO_CLIENT_ID": "your-client-id",
        "ZOHO_CLIENT_SECRET": "your-client-secret",
        "ZOHO_REFRESH_TOKEN": "your-refresh-token",
        "ZOHO_REGION": "com"
      }
    }
  }
}

Run python from the project directory (or set "cwd" / use an absolute interpreter path from your venv). A ready-to-edit claude_config.json ships in this repo. Restart Claude Desktop and the zoho-recruit tools appear.

Test the connection

With the MCP Inspector (HTTP transport):

MCP_TRANSPORT=http python -m src.server --transport http --port 8000
# Inspector connects to: http://localhost:8000/mcp

Or directly over stdio:

python -m src.server          # waits for an MCP client on stdin/stdout

5. Docker

cp .env.example .env          # fill in credentials
docker compose up --build

The container runs the HTTP transport on port 8000; the MCP endpoint is http://localhost:8000/mcp.

6. Available MCP tools

Candidate management

Job management

Interview management

Recruitment analytics

Email automation

Advanced AI assist

7. Errors

Every tool returns either a result or a stable error object:

{ "error_code": "ZOHO_TOKEN_EXPIRED", "message": "Refresh token is invalid or revoked. ..." }

Common codes: ZOHO_TOKEN_EXPIRED, ZOHO_AUTH_FAILED, ZOHO_RATE_LIMITED, ZOHO_RECORD_NOT_FOUND, INVALID_INPUT, NETWORK_ERROR, ZOHO_API_ERROR, ENDPOINT_NOT_CONFIGURED.

The client retries transient failures (429/5xx/network) with exponential backoff and transparently refreshes the access token on a 401.

8. Security & logging

• Only the refresh token is stored; access tokens live in memory and rotate.

• Structured logs capture request id, tool name, execution time, and status.

• Logs never contain tokens, secrets, candidate emails/phones, or resume text — these are redacted by the logger.

• A client-side rate limiter caps requests per minute (RATE_LIMIT_PER_MINUTE).

• All tool inputs are validated (pydantic models / explicit checks).

9. Testing

pip install -r requirements.txt
pytest -q

Tests cover authentication, the HTTP client (retry / 401 / error mapping), domain logic, the AI helpers, and end-to-end flows against a mocked Zoho API (respx). No real Zoho calls are made.

10. Endpoints that may need confirmation for your account

Zoho field/module API names and a few action endpoints vary by edition and by any customisations in your org. These are centralised and clearly commented in the code so you can adjust them in one place:

• Module names — src/zoho/common.py (Candidates, Job_Openings, Interviews).

• Candidate ↔ job association / stage change — JobsAPI.get_pipeline and JobsAPI.change_candidate_stage (/Job_Openings/{id}/associate).

• Candidate email send action — src/zoho/email.py (_SEND_MAIL_PATH).

• Zoho Resume Parser — AIHelpers.resume_parse(use_zoho_parser=True) (the local heuristic parser works out of the box without it).

• Custom field names (e.g. Hiring_Manager, Start_DateTime, Duration) — adjust in the relevant domain module if your template differs.

The local heuristics (match scoring, transcript summarisation, resume text parsing) work without any Zoho-specific configuration.