# 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

```bash
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:

```bash
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?"**

```text
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?"**

```text
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."**

```text
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 `raise`s 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

```bash
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/>.