Simpro → Claude Connector

An MCP server that lets Claude read and act on a Simpro instance. Ask Claude about your jobs, customers and quotes in plain language and it queries Simpro directly — no exports, no copy-paste.

You:    Which Harborview jobs are still open, and what's holding up the board upgrade?

Claude: [calls search_customers, then list_jobs, then get_job]

        Two open for Harborview Property Group:

        #20841  Annual fixed wire testing        In Progress   £4,820.00   due 4 Sep
        #20871  Distribution board upgrade       Pending       £6,390.00   due 25 Sep

        The board upgrade is waiting on parts — purchasing noted a three week
        lead time on 26 August, with the board due the week of 16 September.

Writes are off by default. Out of the box Claude can read Simpro and nothing else. The two tools that change data — adding a note and moving a job's stage — are only advertised when you explicitly enable them. An assistant that can read your job list is useful; one that can quietly change it is a liability.

It runs before you have a token. Demo mode serves realistic built-in data, so you can install it, open Claude and see exactly how it behaves before handing over API credentials.

Tools

* Only offered when SIMPRO_ALLOW_WRITES=true.

Related MCP server: Jobber MCP Connector

Install

Requires Python 3.10 or newer.

git clone https://github.com/memethzmli-ctrl/simpro-claude-connector.git
cd simpro-claude-connector
pip install -e .

Try it without a Simpro account

simpro-connector demo

This runs a scripted set of tool calls against the bundled sample data and prints exactly what Claude receives:

simpro-claude-connector 1.0.0 - demo mode (built-in sample data, no network calls)

search_customers(search='harborview')
[
  {
    "id": 4101,
    "name": "Harborview Property Group",
    "type": "Company",
    "email": "facilities@harborview.example",
    "phone": "+44 1482 555 0117",
    "address": "Unit 7, Prospect Business Park, Hull HU2 8PZ",
    "archived": false
  }
]

list_jobs(stage='Pending')
[
  {
    "id": 20860,
    "name": "Emergency lighting installation - science block",
    "customer_name": "St Chad's Academy Trust",
    "stage": "Pending",
    "status": "Awaiting customer approval",
    "due_date": "2026-10-16",
    "total_ex_tax": 18740.0,
    "currency": "GBP"
  },
  ...
]

Two other commands help when something looks wrong:

simpro-connector check    # print the resolved config and make one real call
simpro-connector tools    # print the tool schemas exactly as Claude sees them

Connect it to Claude Desktop

Add this to claude_desktop_config.json and restart Claude Desktop. The full annotated version is in examples/.

{
  "mcpServers": {
    "simpro": {
      "command": "simpro-connector",
      "args": ["serve"],
      "env": { "SIMPRO_MODE": "demo" }
    }
  }
}

Start in demo mode. Once Claude is answering from the sample data, switch to live.

Going live

Then confirm the connection before touching Claude:

SIMPRO_MODE=live \
SIMPRO_BASE_URL=https://acme.simprosuite.com/api/v1.0 \
SIMPRO_ACCESS_TOKEN=... \
simpro-connector check

A bad token, an unreachable host or a timeout each produce a plain sentence saying what to fix, not a stack trace.

Design notes

Configuration, not hard-coding. Simpro is tenant-hosted: every customer has their own host, company id and credentials. Nothing outside config.py knows a URL, so pointing this at a different instance is environment variables, not a code change.

Tolerant field mapping. Simpro payloads vary slightly between instance versions, so client.py accepts several plausible keys per field and normalises them into one stable shape. Adapting to a specific customer's Simpro is a change in one small module rather than a rewrite, and the tool layer never sees a raw payload.

Two guards on writes, not one. Write tools are hidden from Claude when writes are disabled and the dispatcher refuses them if called anyway. Each write is narrow and validated — there is no generic "update job" accepting arbitrary fields.

Errors are answers. A failed call returns readable text rather than raising, so Claude can tell the person what went wrong and what to do about it instead of just failing.

Demo mode is a real rehearsal. Both backends implement the same interface, so a tool that works against the sample data works against a live instance.

Tests

pip install -e ".[dev]"
pytest

45 tests covering configuration validation, tool schemas, read-only enforcement, filtering and search, pagination against a stubbed transport, every HTTP error path, field normalisation — and four end-to-end tests that launch the real MCP server as a subprocess and drive it with an MCP client, exactly as Claude Desktop does.

Adapting it

• simpro_connector/tools.py — add or reshape the tools Claude is offered

• simpro_connector/client.py — endpoint paths and field mapping for a specific instance

• simpro_connector/fixtures.py — sample data for demo mode

License

MIT