AppFolio MCP Server v2

A Model Context Protocol (MCP) server that wraps AppFolio's REST API so Claude can call it natively in any conversation — the same way Quo works. 38 tools covering portfolio structure, leasing, financials, maintenance, and admin.

When this is deployed and connected, you can say things like:

• "Pull the rent roll for Greensborough Village."
• "Build a Cash P&L for 215 Union St for Q1 2026."
• "Show me work orders open more than 30 days."
• "Which vendors have expired insurance?"
• "What's our monthly cash flow at Russellville this year?"

And Claude calls the AppFolio API directly.

---

⚠️ Important note on budgets

AppFolio's public API does NOT expose a /budgets endpoint. I can pull actuals from the GL all day (that's what build_pl_summary and build_cash_flow do), but the budget side has to come from somewhere else:

• AppFolio's UI exports (you can download budget reports as XLSX from inside AppFolio)
• A Google Sheet of your budgets, attached to a Claude conversation
• A planning doc in Notion or Drive

Once budgets are available in the conversation, Claude can do budget-vs-actual comparisons against the actuals this server returns. If AppFolio adds a budgets endpoint to a newer API version, the pattern to add it is identical to the existing tools — let me know and I'll wire it up.

What this server gives you on the financial side:

• P&L summary (build_pl_summary) — income / expense / NOI by GL account for a property and date range
• Cash flow by month (build_cash_flow) — monthly trend of cash in / cash out / net
• All the raw underlying data (get_gl_details, get_gl_accounts, get_journal_entries, get_bank_accounts)

For the actual official month-end reports you sign off on, keep using AppFolio's UI — this server is for the day-to-day questions you'd otherwise have to log in to find.

---

What you'll need before starting

1. AppFolio API credentials (you have these):
   • Client ID
   • Client Secret
2. AppFolio Developer ID — log in to AppFolio → click your account name (top right) → Admin → look for the Developer ID card. Copy that UUID.
3. A Cloudflare account (free tier): https://dash.cloudflare.com/sign-up
4. Node.js 20+ installed locally: https://nodejs.org
5. Git (optional).

No server to rent, no domain to buy. Cloudflare gives you a free *.workers.dev URL.

---

Step-by-step deployment (~15 minutes the first time)

1. Install dependencies

npm install

2. Log into Cloudflare

npx wrangler login

3. Set the three secrets

npx wrangler secret put APPFOLIO_CLIENT_ID
npx wrangler secret put APPFOLIO_CLIENT_SECRET
npx wrangler secret put APPFOLIO_DEVELOPER_ID

Paste each value when prompted.

4. Deploy

npm run deploy

You'll get a URL like https://appfolio-mcp.<your-subdomain>.workers.dev. Test it in a browser — root should return a JSON health check showing 38 tools.

5. Connect it to Claude

1. Settings → Connectors → Add custom connector
2. Name: AppFolio
3. URL: https://appfolio-mcp.<your-subdomain>.workers.dev/sse
4. Save.

Claude discovers all 38 tools. Done.

---

Tool catalog

Portfolio & structure (7)

Tool	Purpose
get_properties	List properties; filter by type or date
get_property_groups	Property groupings (e.g. by city or manager)
get_portfolios	Top-level portfolios
get_units	Units across portfolio
get_unit_types	Unit type / floor-plan definitions
get_owners	Property owners
get_owner_groups	Ownership groups + percentages

Leasing & occupancy (8)

Tool	Purpose
get_tenants	Tenants; filter by status (Current/Past/Future/Notice)
get_rent_roll	Composite — units + current tenants joined
get_leases	Lease records
get_lease_renewal_pricings	Approved renewal pricing options
get_leads	Leasing leads / guest cards
get_rental_applications	Applications by property/unit/date
get_showings	Tour appointments
get_listings	Active marketing listings

Financial — receivables (4)

Tool	Purpose
get_charges	Open charges (good for duplicate detection)
get_delinquent_charges	Past-due charges
get_recurring_charges	Monthly/recurring billings
get_tenant_ledgers	Charges + payments + credits by occupancy

Financial — payables (2)

Tool	Purpose
get_bills	Accounts payable
get_payables	Outgoing payments / checks

Financial — GL & reporting (6)

Tool	Purpose
get_gl_accounts	Chart of accounts
get_gl_details	GL transaction detail (raw)
get_journal_entries	Manual journal entries
get_bank_accounts	Bank accounts
build_pl_summary	Composite — P&L by GL account for property + date range
build_cash_flow	Composite — monthly cash in/out/net by month

Maintenance (8)

Tool	Purpose
get_work_orders	Work orders; filter by status
get_work_order_attachments	Photos/PDFs on work orders
get_open_work_orders	Composite — open WOs with vendor + age
get_work_order_aging	Composite — WOs bucketed by 0-7/8-30/31-60/61-90/90+ days
get_vendors	Vendor list
get_vendor_compliance	Composite — expired/expiring insurance/contracts/workers comp
get_inventories	Maintenance parts/supplies inventory
get_inventory_locations	Where inventory is stored

Admin (3)

Tool	Purpose
get_users	AppFolio Property Manager users
get_custom_fields	Custom field definitions
get_jobs	Status of bulk async jobs (from bulk-creates)

All list-type tools auto-paginate up to 3 pages by default (300 records). Override with max_pages (cap 10).

---

Example prompts that exercise the composite tools

Rent roll

"Pull the rent roll for property <id> and tell me what % is occupied vs vacant."

P&L summary

"Build a Cash P&L for Greensborough (<id>) from 2026-01-01 to 2026-03-31. Show NOI."

Cash flow trend

"Run a cash flow report for Russellville for the last 12 months. Highlight the months below $5K net."

Open work orders by age

"Show me work orders open more than 60 days, grouped by property."

Vendor compliance

"Which vendors have insurance expiring in the next 30 days?"

---

Local development

cp .dev.vars.example .dev.vars
# Fill in real credentials in .dev.vars (gitignored).
npm run dev

Local URL: http://localhost:8787/sse.

---

Logs and debugging

npm run logs

Or Cloudflare dashboard → Workers & Pages → appfolio-mcp → Logs.

Common issues:

• 401 from AppFolio: Credentials wrong or missing Developer ID. Re-run all three wrangler secret put commands.
• 403 from AppFolio: Your API user lacks permission for that endpoint. AppFolio gates each endpoint individually on the developer user's profile. Log into AppFolio → Admin → API and check what's enabled.
• get_gl_details returning 400: It requires date_from + date_to AND property_id unless the window is ≤2 days. The composite tools (build_pl_summary, build_cash_flow) handle this for you.
• 429 (rate limit): AppFolio limits are 8/sec, 256/min, 4096/hour. The server retries once. Composite tools can hit rate limits if you query huge date ranges — narrow your window or wait.
• Claude says "tool not found": Refresh the connector (remove and re-add).

---

Adding write operations (CAUTION)

This version is read-only on purpose. Writes (creating bills, updating leads, posting charges) touch money and legal documents. Before adding any create_* or update_* tool:

1. Test in an AppFolio sandbox database — never your live one for first runs.
2. Add a confirmation gate — make Claude require you to type "yes, post bill $X to vendor Y" before the tool fires.
3. Log everything — write to a KV store, R2 bucket, or external log service so you have an audit trail.
4. Scope the API user — create a separate AppFolio developer user with only the permissions needed for those specific writes, not your master one.

When you're ready, ask me to add a specific write tool with these safeguards.

---

Architecture

┌─────────────┐      MCP/SSE      ┌──────────────────┐    HTTPS+Basic    ┌──────────────┐
│  Claude UI  │ ◄────────────────►│  Cloudflare      │ ◄────────────────►│  AppFolio    │
│             │                   │  Worker (this)   │                   │  REST API    │
└─────────────┘                   └──────────────────┘                   └──────────────┘
                                          │
                                          ▼
                                   Cloudflare Secrets
                                   (CLIENT_ID, SECRET,
                                    DEVELOPER_ID)

Composite tools (build_pl_summary, build_cash_flow, get_rent_roll, get_open_work_orders, get_work_order_aging, get_vendor_compliance) make multiple AppFolio API calls server-side and stitch the results together before returning. This keeps Claude's context clean and respects rate limits.

Cost: well within Cloudflare's free tier for personal/small-team use.

---

Files

appfolio-mcp/
├── src/
│   ├── index.ts          # Worker entrypoint — wires up tool modules, /sse + /mcp routing
│   ├── client.ts         # AppFolio REST client — auth, pagination, 429 retry
│   ├── util.ts           # Shared helpers + zod schemas (dateFromSchema, maxPagesSchema, ...)
│   ├── list-tool.ts      # Factory for the common "list entities" tool shape
│   └── tools/
│       ├── portfolio.ts    # Portfolio & structure (7)
│       ├── leasing.ts      # Leasing & occupancy (8), incl. rent roll composite
│       ├── financial.ts    # Receivables, payables, GL & reporting (12), incl. P&L/cash flow composites
│       ├── maintenance.ts  # Work orders, vendors, inventory (8), incl. composites
│       └── admin.ts        # Admin (3)
├── package.json          # Dependencies + npm scripts
├── tsconfig.json         # TypeScript config
├── wrangler.toml         # Cloudflare Worker config
├── .dev.vars.example     # Template for local dev secrets
├── .gitignore
└── README.md             # You are here

Most simple list-style tools (properties, units, owners, vendors, etc.) are registered via registerListTool in list-tool.ts to avoid repeating the same id/property_id/last-updated/pagination boilerplate ~20 times. Tools with required fields, "one of X is required" validation, or multi-call composite logic (build_pl_summary, get_rent_roll, get_vendor_compliance, etc.) are hand-written in their category file.