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:

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

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