Skip to main content
Glama
Zoho FSM MCP Server

Zoho FSM MCP Server

by LogeshR15

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

Installation

git clone <this-repo>
cd zoho-fsm-mcp
npm install
npm run build

Requires Node.js β‰₯ 18.


OAuth setup

  1. Go to the Zoho API Console and create a Self Client (or Server-based Application).

  2. Note the Client ID and Client Secret.

  3. Generate a grant token with the FSM scopes, e.g.:

    ZohoFSM.modules.ALL,ZohoFSM.settings.ALL,ZohoFSM.users.READ
  4. Exchange 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_token from the response.

  5. Copy .env.example to .env and 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

com

accounts.zoho.com

fsm.zoho.com/fsm/v1

eu

accounts.zoho.eu

fsm.zoho.eu/fsm/v1

in

accounts.zoho.in

fsm.zoho.in/fsm/v1

au

accounts.zoho.com.au

fsm.zoho.com.au/fsm/v1

jp

accounts.zoho.jp

fsm.zoho.jp/fsm/v1


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 start

Inspect the tools interactively with the MCP Inspector:

npm run inspect

Configuring Claude Desktop

Edit claude_desktop_config.json:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %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.js

For 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

create_request, get_request, search_requests, update_request

Work Orders

create_work_order, update_work_order, search_work_orders

Appointments

create_appointment, update_appointment, schedule_appointment

Contacts

create_contact, search_contacts

Companies

create_company, search_companies

Estimates

create_estimate

Invoices

create_invoice, mark_invoice_paid

Assets

create_asset, update_asset

Users

list_users, get_user

Workflows

create_service_request, assign_best_technician, complete_job

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

  1. Create (or extend) a file in src/tools/, e.g. parts.ts.

  2. Export a registerXTools(ctx: ServerContext) function.

  3. Inside it, call server.registerTool(name, { title, description, inputSchema }, handler).

    • Define inputSchema as a Zod raw shape.

    • Wrap the handler with withToolLogging(name, ...) for logging + error handling.

    • Build the API payload with buildRecord(...) and call a FSMClient method.

    • Return via ok(data, summary).

  4. 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 tools
assign_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

    B3.4/5.0

    Scored across 24 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case, making them predictable and easy to understand.

    Tool Count4/5

    24 tools cover a broad but appropriate scope for an FSM server, though slightly on the high side; each tool serves a clear purpose.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables 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.
      -
    • A
      license
      A
      quality
      F
      maintenance
      Enables AI assistants to access and manage Jobber field-service data including clients, jobs, invoices, and quotes through natural language interactions.
      6
      79 npm
      MIT