mcp-servicefusion

A Model Context Protocol (MCP) server exposing the Service Fusion REST API to AI agents. Enables AI-assisted field service management: job lookup, customer management, dispatch, invoicing, equipment tracking, and more.

Disclaimer: This is an unofficial, community-built integration. Not affiliated with or endorsed by Service Fusion.

Features

Read tools:

• get_todays_jobs — today's scheduled jobs with assigned techs

• search_jobs — flexible search with filters (status, customer, date range, etc.)

• get_job_details — full job record with expanded relations

• get_customer_jobs — all jobs for a given customer

• search_customers — by name, phone, email, or address

• get_equipment — customer equipment with custom fields

• get_open_invoices — outstanding invoices

• get_techs — technician list

• get_job_statuses, get_job_categories, get_sources — reference data

• get_me — current authenticated user

Create tools:

• create_job, create_customer, create_estimate

API documentation:

• get_api_docs — look up the Service Fusion API reference directly from the MCP connection. Sections: index, jobs, customers, estimates, invoices, techs, data-types, authentication, known-issues, full

Prerequisites

• Node.js ≥ 18

• Service Fusion API credentials (My Office → Developer Settings → API Credentials)

Setup (local / stdio transport)

git clone https://github.com/commair-tools/mcp-servicefusion-public.git mcp-servicefusion
cd mcp-servicefusion
npm install
npm run build
cp .env.example .env
# Edit .env and add SF_CLIENT_ID and SF_CLIENT_SECRET

Claude Desktop

Add to your claude_desktop_config.json (see claude_desktop_config.example.json):

{
  "mcpServers": {
    "service-fusion": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-servicefusion/build/index.js"],
      "env": {
        "SF_CLIENT_ID": "your_client_id_here",
        "SF_CLIENT_SECRET": "your_client_secret_here"
      }
    }
  }
}

Claude Code CLI

claude mcp add service-fusion node /absolute/path/to/mcp-servicefusion/build/index.js \
  -e SF_CLIENT_ID=your_client_id -e SF_CLIENT_SECRET=your_client_secret

Setup (remote / HTTP transport)

The server also supports Streamable HTTP transport for hosted deployments (Railway, Fly.io, Cloud Run, etc.) with OAuth 2.1 authentication.

Environment variables

Deploying to Railway

1. Fork or import this repo on Railway

2. Set the environment variables listed above

3. Railway auto-builds via railway.toml and exposes a public URL

4. Use that URL as your BASE_URL

Authentication

Claude.ai web (OAuth flow): add the server URL (without trailing slash, e.g., https://mcp.example.com/mcp) as a remote MCP connector in Settings. Leave OAuth client ID/secret fields blank — the server advertises discovery metadata so Claude.ai handles the full OAuth handshake automatically. On first connect, you'll be redirected to a browser page to enter your MCP_OAUTH_PIN. After that, tokens auto-refresh for 30 days.

Claude Code / CLI clients: use the static token via the Authorization: Bearer <MCP_AUTH_TOKEN> header.

No authentication: if neither MCP_OAUTH_PIN nor MCP_AUTH_TOKEN is set, the server runs unauthenticated (not recommended for public-facing deployments).

API Reference

The repo includes a complete Service Fusion API reference in service-fusion-api-reference.md, auto-generated from the official RAML spec at docs.servicefusion.com. Agents can access it through the get_api_docs tool at runtime.

To regenerate it after Service Fusion updates their spec:

node scripts/update-api-docs.mjs

Known Issues

/jobs endpoint hangs without sort parameter

As of 2026-04-09, Service Fusion's /jobs list endpoint hangs indefinitely when queried without a sort parameter. This server works around it by defaulting all /jobs list queries to sort=-start_date in src/client.ts. If you see hangs on other endpoints in the future, check whether they require a sort param too.

Equipment is a nested resource

There is no top-level /equipment endpoint. Equipment must be fetched via GET /customers/{customer-id}/equipment. The get_equipment tool handles this by resolving customer_name to customer_id internally.

API Limitations

Confirmed by Service Fusion support:

• No PUT, PATCH, or DELETE on any endpoint (read and create only)

• No native webhook/callback support

• No sandbox/test environment

• Rate limit: 60 requests/minute (server enforces backoff automatically)

Tech Stack

• TypeScript + Node.js

• @modelcontextprotocol/sdk for MCP protocol

• Express for HTTP transport

• OAuth 2.1 with PKCE, Dynamic Client Registration, and resource indicators

License

Business Source License 1.1 — see LICENSE

TL;DR: Free to use, modify, and redistribute (including internally at HVAC businesses to manage your own operations). You may not resell it or offer it as a paid hosted service to third parties. On April 10, 2036 it automatically converts to the Apache License 2.0 (fully permissive).