Simpro MCP Server
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Simpro MCP server
An MCP server for Simpro. It gives an AI agent a set of tools for quotes, jobs, customers, catalogue items, scheduling and billing, plus generic GET/POST/PUT/DELETE tools that reach the rest of the Simpro API (about 1,500 endpoints).
This is an unofficial, third-party project. It is not affiliated with, endorsed by, or supported by Simpro.
The server can create, update and delete records, not just read them. An agent using it can change or delete quotes, jobs, customers and catalogue items in your live Simpro account, in bulk, with no undo. Don't give it to an agent you don't trust, and don't let it run unattended against production.
The software is provided as is, without warranty of any kind. You use it at your own risk.
We built this as an internal tool and run it behind our own MCP gateway (proxy mode). The
.mcpb bundle and broker mode were added for other users and we don't run them ourselves.
Contents
Related MCP server: ServiceTitan MCP Server
Choosing a setup
You want to | Use | Needs |
Use Simpro from Claude Desktop on your own machine | Claude Desktop | |
Use it from Claude Code or another local MCP client | Node.js 24+ | |
Offer a connector your team signs in to individually | Docker (or Node.js 24+), a public HTTPS address | |
Run it behind an MCP gateway that already handles sign-in | Your gateway, Docker or Node.js 24+ |
Every setup needs a Simpro build you can reach and an OAuth app created in it, under Setup → Integrations → API. The local setups (Desktop extension and npx) can use a legacy API key instead of an OAuth app. You'll need:
Value | Where it comes from |
Build URL | The address you log in to, e.g. |
Company ID |
|
Client ID and secret | The OAuth app. Treat the secret like a password. |
Redirect URI | Set on the OAuth app. Each setup below says what it should be. |
API key | Only if you're using a legacy key instead of an OAuth app. Local setups only. |
Claude Desktop extension
Create the Simpro OAuth app as an Authorization Code application, with the redirect URI
http://localhost:8237/callback. If port 8237 is taken on your machine, use another port here and enter the same port in step 4.Download
simpro-mcp-server.mcpbfrom the latest release.In Claude Desktop, go to Settings → Extensions → Advanced settings → Install extension and choose the file.
Fill in the build URL, company ID, client ID and client secret. Leave the authentication mode on
authorization_code.
The first time a tool runs, a browser tab opens at the Simpro login page. Log in, approve access, and close the tab. The extension caches a refresh token, so you won't be asked again unless the token is revoked or expires.
The install screen also offers two other authentication modes:
client_credentialssigns in as the OAuth app itself, with no browser step. Use it for unattended automation. Simpro's audit trail won't show which person made a change.api_keyuses a legacy Simpro API key. Paste the key into the Simpro API Key field and leave the client ID and secret empty. Simpro has deprecated static keys, so use this only if you can't create an OAuth app.
Claude Desktop stores the client secret, refresh token and any API key. Anyone who has them can act in your Simpro build. If one leaks, revoke the OAuth app or key in Simpro and create a new one.
Local MCP client with npx
The server is published to npm as
@ozmarks-group/simpro-mcp-server.
Clients that launch MCP servers as a local command can run it with npx. Register
http://localhost:8237/callback as the redirect URI on the Simpro OAuth app.
Claude Code:
claude mcp add simpro \
--env SIMPRO_BASE_URL=https://yourbuild.simprosuite.com \
--env SIMPRO_COMPANY_ID=0 \
--env SIMPRO_AUTH_MODE=authorization_code \
--env SIMPRO_CLIENT_ID=your-client-id \
--env SIMPRO_CLIENT_SECRET=your-client-secret \
-- npx -y @ozmarks-group/simpro-mcp-serverClaude Desktop (claude_desktop_config.json, under Settings → Developer → Edit
Config), or any client using the same format:
{
"mcpServers": {
"simpro": {
"command": "npx",
"args": ["-y", "@ozmarks-group/simpro-mcp-server"],
"env": {
"SIMPRO_BASE_URL": "https://yourbuild.simprosuite.com",
"SIMPRO_COMPANY_ID": "0",
"SIMPRO_AUTH_MODE": "authorization_code",
"SIMPRO_CLIENT_ID": "your-client-id",
"SIMPRO_CLIENT_SECRET": "your-client-secret"
}
}
}
}To use an API key instead, replace the auth mode, client ID and client secret with
SIMPRO_API_KEY:
"env": {
"SIMPRO_BASE_URL": "https://yourbuild.simprosuite.com",
"SIMPRO_COMPANY_ID": "0",
"SIMPRO_API_KEY": "your-api-key"
}If you leave out SIMPRO_AUTH_MODE, it is worked out from what you set: client_credentials
when both client ID and secret are present, otherwise api_key.
Hosted: OAuth broker
In broker mode the server is an OAuth 2.1 authorisation server in front of Simpro. You add
it to Claude (or another MCP client) as a remote connector. Each person clicks connect, logs
in on the normal Simpro login page, and the agent then acts as them. The server stores no
logins. Each person's Simpro tokens are encrypted, using TOKEN_SEAL_KEY, inside the token
their MCP client holds.
It needs:
A public HTTPS address, e.g.
https://simpro.example.com, on a reverse proxy that terminates TLS and forwards to the container. The container speaks plain HTTP.A Simpro OAuth app with the redirect URI set to that address plus
/callback, e.g.https://simpro.example.com/callback.A single instance without any load-balancing. Sign-in state is held in memory.
With Docker
The image is published to GHCR as ghcr.io/ozmarks/simpro-mcp. The repository's
docker-compose.yml runs it in broker mode. Put it in a directory
with a .env file next to it:
SIMPRO_BASE_URL=https://yourbuild.simprosuite.com
SIMPRO_COMPANY_ID=0
PUBLIC_URL=https://simpro.example.com
SIMPRO_CLIENT_ID=your-client-id
SIMPRO_CLIENT_SECRET=your-client-secret
TOKEN_SEAL_KEY=output-of-openssl-rand-hex-32docker compose up -d
curl http://127.0.0.1:3000/healthz # okTo change any other setting from the
configuration reference, add it under environment: in the
compose file.
The compose file publishes port 3000 on 127.0.0.1 only, for a reverse proxy on the same
host. If your proxy runs in another container, put both on a shared Docker network and
remove the ports: entry.
On platforms like Portainer, deploy the compose file as a stack and set the same variables in the stack's environment settings.
With npx
SIMPRO_TRANSPORT=broker \
SIMPRO_BASE_URL=https://yourbuild.simprosuite.com \
PUBLIC_URL=https://simpro.example.com \
SIMPRO_CLIENT_ID=your-client-id \
SIMPRO_CLIENT_SECRET=your-client-secret \
TOKEN_SEAL_KEY=output-of-openssl-rand-hex-32 \
npx -y @ozmarks-group/simpro-mcp-serverAlways set TOKEN_SEAL_KEY when running this way. Without it the server generates a key
and saves it inside npx's package cache, and everyone is signed out whenever that cache is
cleared or the version changes.
Connecting a client
Add a custom connector in your client with the URL https://simpro.example.com/mcp. The
client is sent to Simpro to log in. There's nothing else to configure.
Any request to /mcp without a valid broker token, including listing the tools, gets
401 Unauthorized. The WWW-Authenticate header points the client at the OAuth metadata,
which is how it knows to start the sign-in.
See docs/deploy.md for the state the broker keeps, health checks and
logging.
Hosted: proxy behind a gateway
In proxy mode the server does no authentication. Each request must carry a Simpro access
token in its Authorization: Bearer header, and the server forwards it to Simpro unchanged.
It doesn't check the token. Simpro decides whether it's valid.
Requests without a token are not rejected. initialize and tools/list succeed, so
anyone who can reach the server can see the tool names and their arguments. A tool call
returns a tool error, "Unauthorized: this request carried no Authorization: Bearer token.",
without contacting Simpro.
Use this only behind an MCP gateway or reverse proxy that signs users in to Simpro and attaches their token. Never expose it to the internet directly: anyone who can reach it can send requests to Simpro with whatever token they have.
Gateways that launch MCP servers as a command can run it with npx:
SIMPRO_TRANSPORT=proxy \
SIMPRO_BASE_URL=https://yourbuild.simprosuite.com \
npx -y @ozmarks-group/simpro-mcp-serverTo run it as a container, see the
proxy mode example in docs/deploy.md.
If your gateway runs its own OAuth flow against Simpro, the authorisation endpoint is
<build URL>/oauth2/login (not /authorize), the token endpoint is
<build URL>/oauth2/token, and the only scope Simpro accepts is openid.
Configuration reference
All settings are environment variables. When running from a source checkout, they can also
go in a .env file at the repository root (see .env.example), or in any
file named by SIMPRO_ENV_FILE. Variables already set in the environment take precedence.
All modes
Variable | Default | |
| (required) | Simpro build address. No path, no trailing slash. |
|
| |
|
|
|
|
| Rows per page when a tool call doesn't specify one. Max 250. |
|
| Results larger than this are withheld and the agent is told to narrow the request. |
|
| Largest attachment the upload tools accept (50 MB). |
|
| Memory all in-progress uploads may use together (200 MB). |
| on | Set to |
stdio
Variable | Default | |
| inferred |
|
| Needed for | |
|
| Port for the login callback. The redirect URI on the OAuth app must be |
| Legacy key, for |
broker and proxy
Variable | Default | |
|
| |
|
| Set to |
|
| The health check is always at |
| Comma-separated allow-lists for the |
The server won't start in either HTTP mode if SIMPRO_API_KEY is set.
broker only
Variable | Default | |
| (required) | The public HTTPS address of the server. |
| (required) | The Simpro OAuth app. |
| generated | 32 bytes as hex or base64 ( |
|
| Only change it if your build uses a different login URL. |
|
| |
| JSON array of pre-registered confidential clients, for connectors that don't use CIMD or dynamic registration. Example in | |
|
| How long the broker holds a rotated Simpro refresh token in memory, so a client that lost a refresh response can retry. |
How the broker handles sign-in
MCP clients such as Claude only connect to authorisation servers that follow OAuth 2.1. Simpro's OAuth is 2.0 without PKCE and without the client registration methods those clients use. The broker acts as the OAuth 2.1 server and passes the actual login through to Simpro. It adds:
PKCE (S256). The client sends a code challenge to
/authorizeand must prove it at/token. Simpro doesn't check PKCE, so the broker does.Client registration without a shared secret. A client can identify itself in two ways:
CIMD: the client ID is a URL to a metadata document. The broker fetches it on each authorisation, checks that it names itself and lists the exact redirect URI in use, and guards the fetch against requests to private network addresses.
Dynamic client registration (RFC 7591): the client calls
POST /registerto get a client ID. Registration is open, so it is rate- and size-limited, the oldest entries are dropped at the cap, and registrations are saved to disk.
Simpro never sees the client's identity. Every login goes to Simpro under the one OAuth app the broker is configured with.
Exact redirect URI matching. Prefix matches are rejected.
Short-lived tokens bound to this server. Clients get tokens issued by the broker, with an expiry and this server as the audience. The Simpro tokens are encrypted inside them. Refresh tokens last at most 30 days.
The broker keeps no token database, with one exception. Simpro invalidates a refresh token when it's used, so if a client loses the response to a refresh it would otherwise have to log in again. To cover that, the broker keeps the newest Simpro refresh token for each login in memory for a few minutes. It is never written to disk and is cleared on the next successful refresh or on restart.
Development
npm install
npm run build # compile to dist/
npm test # unit tests
npm start # run dist/index.js
npm run login # authorization_code login only: cache the refresh token, then exit
npm run build:mcpb # build simpro-mcp-server.mcpbCopy .env.example to .env and fill it in before running: the build URL and company ID,
plus either the OAuth client ID and secret or SIMPRO_API_KEY. npm start uses stdio unless
SIMPRO_TRANSPORT says otherwise.
The unit tests cover the code that doesn't talk to the network: search ranking, output
formatting, line-item paths, and the auth crypto and storage helpers. Nothing mocks Simpro,
so checking a change properly means running it against a real Simpro build. Architecture
notes and Simpro API quirks are in CLAUDE.md.
License
Functional Source License, Version 1.1, ALv2 Future License (FSL-1.1-ALv2).
You can use, modify and redistribute it for any purpose except a Competing Use: offering
it, or something substantially similar, to others as a commercial product or service. Each
release becomes available under the Apache License 2.0 two years after it is published.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Simpro MCP server for ChatGPT, Claude and any AI agent: list jobs, create quote, convert quote to job, update job status, look up customer, check schedule, add schedule entry and search catalogue items in your own Simpro account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Simpro yourself; Cotlet does not store your password and you need no Simpro API key. About the official Simpro API: Simpro has a full REST API with OAuth 2.0 for quotes, jobs, schedules, customers and catalogue items, but no official MCP server (checked 17 Oct 2026). Your administrator creates the API credentials in your build, partner apps need approval from Simpro, and all calls share a limit of 10 per second per build. Setup and FAQ: https://cotlet.dev/integrations/simpro-api-mcp-server
Run a service business from your AI agent: CRM, leads, scheduling, invoicing, jobs and more.
Headless field service software. Your AI agent runs jobs, schedules, quotes, invoices and payments.
Run a home-service business from your AI: jobs, customers, invoices, estimates, texts.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to interact with Fergus job management platform through secure API integration. Supports managing jobs, customers, quotes, and sites with real-time data synchronization.1MIT
- 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-
- AlicenseNot gradedqualityDmaintenanceEnables Claude to query and act on Simpro jobs, customers, quotes, and related data through natural language, with write operations off by default and a demo mode for trying without API credentials.MIT