Zoho FSM MCP Server
Exposes the Zoho FSM (Field Service Management) REST API, providing tools for managing service requests, work orders, appointments, contacts, companies, estimates, invoices, assets, and users, along with intelligent workflow tools and cached resources.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Zoho FSM MCP Server Show me all open work orders"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Zoho FSM MCP Server
A production-ready Model Context Protocol server that exposes the Zoho FSM (Field Service Management) REST API as AI-friendly tools, resources, and prompts.
It is modular and extensible: thin API-wrapper tools, higher-level "intelligent" workflow tools, cached read-only resources, and a dedicated extension point for tools auto-generated from an OpenAPI spec.
Features
π OAuth with automatic access-token refresh (refresh-token grant), multi-region.
π Single API client (
FSMClient) with retries, backoff, timeouts, 401 recovery, and typed responses.π§° Tools for Requests, Work Orders, Appointments, Contacts, Companies, Estimates, Invoices, Assets, and Users.
π€ Intelligent workflow tools that orchestrate multiple API calls (
create_service_request,assign_best_technician,complete_job).π Resources (
fsm://modules,fsm://statuses,fsm://territories,fsm://users,fsm://services,fsm://parts,fsm://metadata) with TTL caching.π¬ Prompt templates (
dispatch-summary,job-summary,invoice-summary,technician-brief,customer-history).πͺ΅ Structured logging to stderr (never logs secrets) and centralized error handling.
π§© Extensible:
src/tools/generated/is reserved for OpenAPI-generated tools.
Related MCP server: ServiceTitan MCP Server
Project structure
zoho-fsm-mcp/
βββ src/
β βββ auth/oauth.ts # OAuth token manager (refresh + caching)
β βββ client/
β β βββ fsmClient.ts # The only place HTTP happens
β β βββ types.ts # Shared FSM/response types
β βββ tools/
β β βββ requests.ts workOrders.ts appointments.ts contacts.ts
β β βββ companies.ts invoices.ts estimates.ts assets.ts users.ts
β β βββ intelligent.ts # Multi-step workflow tools
β β βββ generated/ # Reserved for OpenAPI-generated tools
β β βββ shared.ts # Shared Zod shapes + context type
β β βββ index.ts # registerAllTools()
β βββ resources/ # modules, statuses, metadata (+ live)
β βββ prompts/ # Reusable prompt templates
β βββ utils/ # config, logger, errors, cache, mcp helpers
β βββ server.ts # Wires everything together
β βββ index.ts # stdio entry point
βββ .env.example
βββ package.json tsconfig.json eslint.config.js .prettierrc
βββ README.mdInstallation
git clone <this-repo>
cd zoho-fsm-mcp
npm install
npm run buildRequires Node.js β₯ 18.
OAuth setup
Go to the Zoho API Console and create a Self Client (or Server-based Application).
Note the Client ID and Client Secret.
Generate a grant token with the FSM scopes, e.g.:
ZohoFSM.modules.ALL,ZohoFSM.settings.ALL,ZohoFSM.users.READExchange the grant token for a refresh token (one-time), using the accounts endpoint for your region:
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 "code=YOUR_GRANT_TOKEN"Save the
refresh_tokenfrom the response.Copy
.env.exampleto.envand fill in:ZOHO_CLIENT_ID=... ZOHO_CLIENT_SECRET=... ZOHO_REFRESH_TOKEN=... ZOHO_REGION=com # com | eu | in | au | jp
The server refreshes access tokens automatically and picks the correct base URL from ZOHO_REGION:
Region | Accounts endpoint | FSM API base |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Running locally
# Development (auto-reload)
npm run dev
# Type-check / lint / format
npm run typecheck
npm run lint
npm run format
# Production
npm run build
npm startInspect the tools interactively with the MCP Inspector:
npm run inspectConfiguring Claude Desktop
Edit claude_desktop_config.json:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"zoho-fsm": {
"command": "node",
"args": ["/absolute/path/to/zoho-fsm-mcp/dist/index.js"],
"env": {
"ZOHO_CLIENT_ID": "...",
"ZOHO_CLIENT_SECRET": "...",
"ZOHO_REFRESH_TOKEN": "...",
"ZOHO_REGION": "com"
}
}
}
}Restart Claude Desktop. The zoho-fsm tools appear in the tools menu.
Configuring ChatGPT / other MCP clients
Any MCP-compatible client that supports stdio servers can launch it the same way:
node /absolute/path/to/zoho-fsm-mcp/dist/index.jsFor ChatGPT's MCP support, register a connector pointing at this command (or wrap it behind an HTTP/SSE bridge if your client requires a URL). Environment variables are supplied the same way as above.
Available tools
Category | Tools |
Requests |
|
Work Orders |
|
Appointments |
|
Contacts |
|
Companies |
|
Estimates |
|
Invoices |
|
Assets |
|
Users |
|
Workflows |
|
Every tool validates input with Zod, calls FSMClient, and returns a structured MCP response. Errors are converted into a consistent payload with status, code, retryable, message, and details.
Adding a new tool
Create (or extend) a file in
src/tools/, e.g.parts.ts.Export a
registerXTools(ctx: ServerContext)function.Inside it, call
server.registerTool(name, { title, description, inputSchema }, handler).Define
inputSchemaas a Zod raw shape.Wrap the handler with
withToolLogging(name, ...)for logging + error handling.Build the API payload with
buildRecord(...)and call aFSMClientmethod.Return via
ok(data, summary).
Register your function in
src/tools/index.ts.
Example skeleton:
export function registerPartTools({ server, client }: ServerContext): void {
server.registerTool(
'create_part',
{ title: 'Create Part', description: '...', inputSchema: { name: z.string() } },
withToolLogging('create_part', async (args) => {
const created = await client.create('Parts', buildRecord({ Name: args.name }));
return ok(created, `Created part "${args.name}".`);
}),
);
}New REST calls should go through FSMClient (add a method there) β never call axios directly from a tool.
Future: OpenAPI-generated tools
src/tools/generated/ is reserved for tools generated from the Zoho FSM OpenAPI spec. A codegen step will emit *.generated.ts files there, each exporting a registerβ¦GeneratedTools(ctx) function called from generated/index.ts. Generated code stays separate from the hand-written intelligent tools and is safe to regenerate wholesale.
License
MIT
Available Tools
24 toolsassign_best_technicianAssign Best TechnicianA
Pick the most suitable technician for a Work Order and assign them. Technicians are filtered by territory and (optionally) required skills, then the least-loaded match is selected. Returns the chosen technician and the updated work order.
Inputs: work_order_id (required), territory_id, required_skills.
complete_jobComplete JobA
Close out a job: mark the Service Appointment complete, set the Work Order to Completed, and optionally generate an Invoice from the provided line items. Returns a consolidated summary of everything that was updated.
Inputs: work_order_id (required), appointment_id (required), company_id, line_items, +2 more.
create_appointmentCreate Service AppointmentB
Create a Service Appointment for a Work Order, optionally assigning a technician and a scheduled start/end time.
Inputs: work_order_id (required), summary, scheduled_end, technician_id, +2 more.
create_assetCreate AssetB
Create an Asset (a piece of serviceable customer equipment) in Zoho FSM, associated with a company and optionally a contact.
Inputs: name (required), company_id (required), contact_id, product_id, +2 more.
create_companyCreate CompanyB
Create a customer Company (account) in Zoho FSM.
Inputs: name (required), email, phone, website, +1 more.
create_contactCreate ContactC
Create a Contact in Zoho FSM. A first name is required; email and phone are strongly recommended so the contact can be matched and notified later.
Inputs: last_name (required), email, phone, mobile, +3 more.
create_estimateCreate EstimateB
Create an Estimate (quote) in Zoho FSM for a customer, optionally tied to a Request or Work Order, with priced line items.
Inputs: company_id (required), summary, contact_id, line_items, +2 more.
create_invoiceCreate InvoiceA
Create an Invoice in Zoho FSM for a completed job. Line items are provided as an array of { name, quantity, rate } objects.
Inputs: company_id (required), contact_id, line_items, work_order_id, +1 more.
create_requestCreate Service RequestA
Create a new service Request in Zoho FSM. A Request is the initial intake record capturing what a customer needs before a Work Order is scheduled. Requires at least a summary and the associated company or contact.
Inputs: summary (required), due_date, priority, company_id, +3 more.
create_service_requestCreate Service Request (guided)A
End-to-end intake: find or create the customer, then file a Request and return a summary. If a company name is given, an existing company is matched; if none is found and create_if_missing is true, one is created. Prefer this over the raw create_request tool when starting from a customer name rather than an ID.
Inputs: summary (required), customer_name (required), priority, description, +1 more.
create_work_orderCreate Work OrderC
Create a Work Order in Zoho FSM. A Work Order defines the job to be performed for a customer, including the company, contact, service type, and priority.
Inputs: summary (required), due_date, priority, company_id, +4 more.
get_requestGet Service RequestA
Fetch a single FSM Request by its record ID.
Inputs: request_id (required).
get_userGet UserA
Fetch a single FSM user by their user ID.
Inputs: user_id (required).
list_usersList UsersA
List the FSM users (agents, dispatchers, field technicians) in the organization. Useful for finding technician IDs to assign to appointments.
Inputs: page, fields, per_page.
mark_invoice_paidMark Invoice PaidA
Mark an existing Invoice as Paid by updating its status.
Inputs: invoice_id (required).
schedule_appointmentSchedule Service AppointmentA
Run the "schedule" blueprint transition on a Service Appointment, assigning a technician and a confirmed time window. Use this instead of update_appointment when you want to formally move the appointment into the Scheduled state.
Inputs: scheduled_end (required), technician_id (required), appointment_id (required), scheduled_start (required), +1 more.
search_companiesSearch CompaniesA
Search Companies by free-text word or a Zoho criteria expression. Provide one of word or criteria.
Inputs: page, word, fields, criteria, +1 more.
search_contactsSearch ContactsA
Search Contacts by free-text word, email, phone, or a Zoho criteria expression. Provide exactly one of word, email, phone, or criteria.
Inputs: page, word, email, phone, +3 more.
search_requestsSearch Service RequestsA
Search Requests using a Zoho criteria expression, e.g. (Priority:equals:High) or (Summary:starts_with:AC). Supported operators include equals, not_equal, contains, starts_with, greater_than, less_than.
Inputs: criteria (required), page, fields, per_page.
search_work_ordersSearch Work OrdersA
Search Work Orders with a Zoho criteria expression, e.g. (Status:equals:Open) or (Priority:equals:High).
Inputs: criteria (required), page, fields, per_page.
update_appointmentUpdate Service AppointmentC
Update fields on an existing Service Appointment.
Inputs: appointment_id (required), status, summary, scheduled_end, +3 more.
update_assetUpdate AssetC
Update fields on an existing Asset.
Inputs: asset_id (required), name, status, serial_number, +1 more.
update_requestUpdate Service RequestC
Update fields on an existing FSM Request. Only provided fields are changed.
Inputs: request_id (required), status, summary, priority, +2 more.
update_work_orderUpdate Work OrderC
Update fields on an existing Work Order. Only provided fields are changed.
Inputs: work_order_id (required), status, summary, priority, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 24 tools
Most tools have distinct purposes, but there is potential confusion between create_appointment and schedule_appointment, as well as between create_request and create_service_request, though descriptions clarify.
All tool names follow a consistent verb_noun pattern in snake_case, making them predictable and easy to understand.
24 tools cover a broad but appropriate scope for an FSM server, though slightly on the high side; each tool serves a clear purpose.
The tool set covers the core lifecycle from request to invoicing, but lacks delete operations and some advanced FSM features like inventory or territory management.
Maintenance
Related MCP Connectors
Job management for service companies: look up, book, tag, assign and note jobs from your AI.
Your field-service business in your assistant: clients, requests, schedule, jobs, quotes, invoices.
Run field service from Claude, ChatGPT or Copilot: dispatch, billing, customer messages, photos, and change the software itself, with a confirm step before every change. This address is the India region; US East, Canada, Norway and NZ addresses are at fieldproxy.ai/mcp.
Read FieldPulse customers, jobs, estimates, invoices, assets and projects; create and update jobs.
Related MCP Servers
- -licenseNot gradedqualityNot gradedmaintenanceEnables AI agents to interact with ServiceFusion's field service management platform through standardized MCP operations. Supports complete customer and job management including creating work orders, managing customer records, and accessing service data with OAuth 2.0 authentication.-
- AlicenseNot gradedqualityDmaintenanceProvides AI assistants with direct access to ServiceTitan's field service management platform for home services contractors. It enables users to manage customers, jobs, appointments, technician dispatching, and invoices through natural language.1MIT
- FlicenseAqualityDmaintenanceEnables AI-assisted field service management through the Service Fusion API, including job lookup, customer management, dispatch, invoicing, and equipment tracking.161-
- AlicenseAqualityFmaintenanceEnables AI assistants to access and manage Jobber field-service data including clients, jobs, invoices, and quotes through natural language interactions.679 npmMIT