cincsystems-mcp

First MCP server for the CINC Systems (HOA / community association management) REST API. 50K+ communities, 6M+ doors, $11B+ annual payments processed.

CINC Systems is the leading US community-association-management (CAM / HOA / condo) platform. Management companies use it to run the back-office accounting, board packets, ACC (Architectural Control Committee) workflow, homeowner communications, vendor management, and aged-balance collections for the HOAs, condominiums, lifestyle communities, and high-rises they manage.

cincsystems-mcp exposes the CINC Systems V1 REST API as 13 MCP tools so Claude / Cursor / any MCP client can read and (for ACC and vendors) write to your CINC account in plain English.

What this unlocks

• ACC triage: "Show me every pending ACC request in HOA 42, sorted by submission date."
• Aged balances report: "Who's 90+ days past due across all our HOAs?"
• Collections escalation: "Pull the flagged-collections list for HOA 88 and draft a referral-to-attorney email for the top 3."
• Board packet drafting: "What charges were posted in HOA 142 last quarter?"
• Document lookup: "Where are the CC&Rs for Cypress Run?"
• Vendor tracking: "List every vendor whose insurance is on file in HOA 42."
• Call log audit: "Show me this week's call log for HOA 42."

Quick start

pip install -e .

export CINC_SYSTEMS_API_KEY=<opaque-token>
export CINC_SYSTEMS_MGMT_ID=<integer>
export CINC_SYSTEMS_BASE_URL=https://<your-subdomain>.cincsys.com

cinc_systems_mcp

Or run it via mcp directly:

mcp run src/cinc_systems_mcp/server.py

Auth

CINC Systems V1 is per-tenant. Each management company has its own subdomain and its own mgmt_id integer. You need three values:

Env var	What it is	Where to get it
CINC_SYSTEMS_API_KEY	Opaque API key (NOT Bearer-prefixed)	CINC UI -> Account -> API Settings
CINC_SYSTEMS_MGMT_ID	Per-tenant integer (e.g. 1234)	CINC UI -> top-right menu -> API Settings
CINC_SYSTEMS_BASE_URL	Per-tenant base URL (e.g. https://acme.cincsys.com)	The URL you log in to

The V1 API uses a plain Authorization: <api_key> header. CINC's V1 server rejects Bearer -prefixed tokens; this client uses the opaque-token form.

Tools

13 tools total. All read the CINC account scoped to your mgmt_id.

Diagnostic

• health_check — verify the API key, mgmt_id, and base URL are all valid

Associations

• list_associations(assoc_code=None) — list all HOAs/condos you manage
• get_association(assoc_code) — get one HOA by its code

Homeowners

• list_homeowners(assoc_code=None, last_name=None) — list homeowners
• get_homeowner(homeowner_id) — get one homeowner by ID

ACC (Architectural Control Committee)

• list_acc(assoc_code=None, status=None) — list architectural review requests
• create_acc(body) — log a new ACC request (e.g. paint, fence, addition)

Vendors

• list_vendors(assoc_code=None) — list contractors you use
• update_vendor(vendor_id, body) — update vendor record (insurance, contact)

Aged Balances

• list_aged_balances(assoc_code=None) — delinquent accounts by 30/60/90+ day buckets

Call Logs

• list_call_logs(assoc_code=None, days=None) — inbound/outbound HOA calls

Documents

• list_documents(assoc_code=None, doc_type=None) — CC&Rs, bylaws, minutes, contracts

Flagged Collections

• list_flagged_collections(assoc_code=None) — accounts escalated to attorney

Post Charges

• list_post_charges(assoc_code=None, since=None) — recently posted assessments/fines/fees

Real workflow examples

Q: "Who in HOA 42 is 90+ days past due?"

Use list_aged_balances(assoc_code="HOA042") to pull the aging report.
The response is a list of records broken into 30/60/90+ day buckets.
Surface the 90+ bucket and the homeowner IDs in it.

Q: "What architectural requests came in this week?"

Call list_acc(assoc_code=None, status="pending") and filter to the
last 7 days on the assistant side. Each record has assocCode,
homeownerId, description, requestType, and submission timestamp.

Q: "Log a paint request for homeowner 9876 in HOA 42."

Call create_acc(body={
  "assocCode": "HOA042",
  "homeownerId": "9876",
  "description": "Repaint front door navy blue",
  "requestType": "paint"
}). The response is the new ACC record.

Architecture

Built on industry-leading Python patterns (see ~/.mavis/agents/mavis/memory/engineering-playbook.md):

• Shared httpx.AsyncClient with connection pooling and transport-level retries for transient network failures.
• Typed exception hierarchy — CincSystemsAuthError / NotFoundError / RateLimitError / APIError / ConnectionError with structured fields (http_status, error_code, request_id, retry_after).
• Application-level retry with exponential backoff + full jitter on 429 and 5xx, honoring the Retry-After header.
• Dispatch table for HTTP status -> exception (one row per status, no chained if/raise).
• isError-compliance — every tool raises on failure so FastMCP sets isError=true on the wire response (the Blackwell Systems MCP audit found 9 of 25 default-input crashes + 11 silent-error patterns in popular MCPs; we don't repeat that mistake).
• JSONL audit logging — every tool call writes a structured record to stderr (or a file via CINC_SYSTEMS_AUDIT_LOG) with secret redaction.
• respx + hypothesis tests — 25+ tests, ruff + mypy --strict clean.

Testing

pip install -e ".[dev]"
pytest          # 25+ tests, no live API
ruff check src tests
ruff format --check src tests
mypy src

License

MIT.

Related MCPs

Other first-party MCPs in this series:

• sanjibani/hawksoft-mcp — insurance
• sanjibani/open-dental-mcp — dental
• sanjibani/ezyvet-mcp — veterinary
• sanjibani/jobber-mcp — home service
• sanjibani/practicepanther-mcp — legal practice
• sanjibani/cox-automotive-mcp — auto dealership
• sanjibani/qualia-mcp — title and escrow
• sanjibani/realm-mp-mcp — church / nonprofit
• sanjibani/fieldroutes-mcp — pest control / lawn care
• sanjibani/campspot-mcp — outdoor hospitality
• sanjibani/cleancloud-mcp — laundry / dry cleaning
• sanjibani/playmetrics-mcp — youth sports
• sanjibani/foreup-mcp — golf course management
• sanjibani/storedge-mcp — self-storage
• sanjibani/courtreserve-mcp — racquet sports
• sanjibani/procare-mcp — child care
• sanjibani/passare-mcp — deathcare / funeral
• sanjibani/funraise-mcp — nonprofit fundraising
• sanjibani/kicksite-mcp — martial arts
• sanjibani/singleops-mcp — green industry

Browse the full list at https://github.com/sanjibani?q=-mcp.

For custom MCP engagements, see https://sanjibani.github.io/mcp-services/.