AccuLynx MCP server

AccuLynx MCP Server & CLI

npm: acculynx-mcp (MCP server) · @opsrev/acculynx-cli (CLI + MCP)

An MCP server for the AccuLynx roofing CRM — bring jobs, contacts, and estimates into Claude Desktop, Cursor, or any MCP client. Every tool is exposed with an enforced JSON Schema, so an AI agent can't invent a parameter or call a command that doesn't exist.

• 30 tools across jobs, contacts, estimates, and users.
• acculynx-mcp — the MCP server, for Claude Desktop / Cursor / any MCP client.
• @opsrev/acculynx-cli — the same data as a JSON CLI (and it also ships the acculynx-mcp server bin).

Use in Claude Desktop

1. Get an AccuLynx API key (your AccuLynx account administrator creates it under Account Settings → API).
2. Open your Claude Desktop config file:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
3. Add the server (zero-install via npx):

{
  "mcpServers": {
    "acculynx": {
      "command": "npx",
      "args": ["-y", "acculynx-mcp"],
      "env": { "ACCULYNX_API_KEY": "your-api-key" }
    }
  }
}

Prefer a global install? Run npm i -g acculynx-mcp, then use "command": "acculynx-mcp" with no args.

1. Restart Claude Desktop. Open a new chat and ask "List my 5 most recent AccuLynx jobs" — you should see the acculynx_* tools available.

Use in Cursor / other MCP clients

Any client that speaks MCP over stdio works. Point it at npx -y acculynx-mcp (or a global acculynx-mcp) and set ACCULYNX_API_KEY in the environment. Example (Cursor ~/.cursor/mcp.json):

{
  "mcpServers": {
    "acculynx": {
      "command": "npx",
      "args": ["-y", "acculynx-mcp"],
      "env": { "ACCULYNX_API_KEY": "your-api-key" }
    }
  }
}

MCP tools

All tools are prefixed acculynx_ and return JSON.

Tool	Description
acculynx_ping	Health check — verify the API key and connectivity
acculynx_jobs_list	List jobs (paginated, filterable)
acculynx_jobs_get	Get one job by id
acculynx_jobs_create	Create a job
acculynx_jobs_search	Search jobs by free-text term
acculynx_jobs_contacts	List a job's contacts
acculynx_jobs_estimates	List a job's estimates
acculynx_jobs_financials	Get a job's financials
acculynx_jobs_invoices	List a job's invoices
acculynx_jobs_milestones	List a job's milestone history
acculynx_jobs_payments	List a job's payments
acculynx_jobs_history	Get a job's change history
acculynx_jobs_reps	List a job's representatives
acculynx_jobs_reps_assign	Assign a representative to a job
acculynx_jobs_work_types	List the company's active work types (id + name)
acculynx_jobs_trade_types	List the company's active trade types (id + name)
acculynx_jobs_set_work_type	Set a job's work type — by workType name or workTypeId
acculynx_jobs_set_trade_types	Set a job's trade types — by tradeTypes names or tradeTypeIds (empty array unassigns all)
acculynx_jobs_document_folders	List the company's document folders
acculynx_jobs_add_expense	Record an additional expense on a job
acculynx_jobs_upload_document	Upload a local file to a job
acculynx_contacts_list	List contacts (paginated)
acculynx_contacts_get	Get one contact by id
acculynx_contacts_create	Create a contact
acculynx_contacts_search	Search contacts within a date range
acculynx_contacts_emails	List a contact's email addresses
acculynx_contacts_phones	List a contact's phone numbers
acculynx_contacts_phone_add	Add a phone number to a contact
acculynx_estimates_list	List estimates (paginated)
acculynx_estimates_get	Get one estimate by id
acculynx_estimates_sections	List an estimate's sections
acculynx_estimates_section	Get one estimate section
acculynx_estimates_items	List items in an estimate section
acculynx_users_list	List users (paginated, optional name/email search)

Configuration

Env Var	Flag	Required	Description
ACCULYNX_API_KEY	--api-key	Yes	AccuLynx official API key (Account Settings → API)
ACCULYNX_EMAIL	—	No	Login email; only for tools that use AccuLynx's web API
ACCULYNX_PASSWORD	—	No	Login password; only for web-API tools
ACCULYNX_COMPANY_ID	—	No	Company GUID; only for web-API tools

Also a CLI

@opsrev/acculynx-cli exposes the same data as a JSON CLI (and bundles the acculynx-mcp server bin). All output is JSON to stdout; errors are {"error": "..."} to stderr with exit code 1.

npm install -g @opsrev/acculynx-cli

acculynx ping                              # verify API key
acculynx jobs list --limit 5               # 25 results by default; --all to fetch everything
acculynx jobs get <jobId>
acculynx jobs search --query "smith"
acculynx jobs scan --milestones Approved   # scan all jobs → digest + coverage receipt
acculynx contacts list --limit 10
acculynx estimates get <estimateId>

List commands default to 25 results; use --limit <n> or --all. Commands that create resources read a JSON body from stdin:

echo '{"name": "New Job"}' | acculynx jobs create

Pipe to jq for scripting:

JOB_ID=$(acculynx jobs list --limit 1 | jq -r '.[0].id')
acculynx jobs get "$JOB_ID" | jq .

Prospect aging with complete readable rows

acculynx jobs scan --report prospect-aging --as-of 2026-10-20 --exclude-trade-type "Maintenance Program"

This bounded GET-only report ages current Prospect inventory by its full milestone date in America/New_York, with inclusive 0–30, 31–60, 61–90 and 91+ calendar-day buckets. It is not a historical inventory snapshot. Exclusions use exact case-insensitive trade-type names; missing classification stays unknown. Every eligible row includes its full ID, date, age and separate approved/worksheet values in exact cents. Missing values remain unavailable rather than zero.

Enumeration is strict and capped at 5,000 jobs before per-job financial reads. Reports above 180,000 characters return partial with no detailed list, keeping output below the retained process-log limit. No history, payment, message or write requests are made. Invalid/incomplete inventory withholds totals and rows; missing dates or financial evidence make the result partial (exit 3). Incompatible filters and output modes fail before provider access (exit 2). Read long stdout through bounded process-log pages.

Monitoring scans: payments with strict coverage

Scan every job in a set of milestones and fetch each one's received payments in one process, with a coverage line a script can check:

acculynx jobs scan --milestones Approved,Completed,Invoiced \
  --enrich payments --strict --format jsonl --out payments.jsonl

Each job line carries payments: the job's full received-payment objects (id, from, amount, paymentDate, checkNumber, notes, …). The last line is the coverage receipt:

{"type":"coverage","scanned":299,"serverCount":299,"complete":true,"pageError":null,"enrichErrors":0}

• --strict (implied by --enrich payments) treats any pagination anomaly (changing total, duplicate job IDs, overfull or malformed pages) as a partial scan. Partial scans exit 3 and report complete: false. Never treat them as a full inventory.
• A per-job payments failure doesn't abort the scan. It appears in that job's errors ({"jobId", "source": "payments", "message"}) and counts toward enrichErrors, so retry just those jobs with acculynx jobs payments <id>.
• Without --strict and without payments, jsonl output is unchanged: job lines only.

Development

cp .env.example .env   # fill in your credentials
npm install
npm test               # run unit tests (mocked fetch)
npm run dev -- --help  # run the CLI in dev mode (auto-loads .env)
npm run build          # build both bins to dist/

npm run dev auto-loads .env via Node's --env-file:

npm run dev -- jobs list --limit 5

License

MIT

Private marketing evidence from a native scan

Operators preparing approval-date reconciliation can preserve exact source fields without parsing the rounded human digest:

acculynx jobs scan --start-date 2026-07-01 --end-date 2026-09-04 --date-filter-type ModifiedDate --enrich dates,financials --format marketing-evidence

This emits one acculynx-marketing-evidence/v1 JSON object. It is private operator evidence containing full job IDs and individual values; do not post it in a vendor/customer channel. It excludes contacts, addresses, names, notes, documents, unrelated financials and raw provider error bodies. --out and other enrichers are rejected before reading. Redirect stdout only into an appropriately protected operator workspace if retaining the artifact. This format does not alter downstream agents' command allowlists or authorize them to export records.

The receipt distinguishes query completeness from enrichment completeness. Strict pagination requires a numeric stable total, advancing offsets and unique job IDs. Exit 3 means partial evidence; never publish it as a complete result. Full source dates are preserved without timezone conversion, repeated approval milestones remain separate, and current approved value is represented in exact cents. Missing/invalid values and dates remain null with issue codes.

This is not an approval cohort, an original-acquisition attribution, a complete lead-delivery inventory or historical revenue. ModifiedDate is a candidate filter; confirm historical and unassigned/dead-lead coverage separately. Review source date semantics, repeated approvals, transfers and current-versus-original contract value before producing normalized results. A large historical scan reads history and financials for each candidate; bootstrap it separately from short daily marketing jobs, then validate an incremental refresh strategy.