qobrix-crm-mcp

<p align="center"> <a href="https://sharpsir.group"> <img src="https://raw.githubusercontent.com/sharpsir-group/.github/main/brand/logo-blue.png" alt="SharpSir Group — Sharp Sotheby's International Realty brand logo" width="400" /> </a> </p> <h1 align="center">Qobrix CRM MCP Server</h1> <p align="center"> <strong>Connect Claude.ai, Dust.tt, Cursor, and other MCP clients to your Qobrix real-estate CRM</strong> — listings, leads, viewings, offers, contracts, and activity in one read-only <a href="https://modelcontextprotocol.io/">Model Context Protocol</a> layer.<br /> <strong>64 tools</strong> (CRM entities + AI relevance search + analytics + audit + cache controls + session/identity), <a href="https://www.reso.org/data-dictionary/">RESO Data Dictionary 2.0</a> workflows, optional <strong>Redis-backed response caching</strong>, <strong>four auth modes</strong> (stdio / headers / OAuth elicitation / remote MCP OAuth for <strong>Claude.ai</strong> and <strong>Dust.tt</strong>), and <strong>226+ automated tests</strong>. </p> <p align="center"> <a href="https://github.com/gca-ltd/qobrix-crm-mcp">GitHub</a> · <a href="https://qobrix.com/">Qobrix CRM</a> · <a href="https://claude.ai/">Claude.ai</a> · <a href="https://dust.tt/">Dust.tt</a> · <a href="https://modelcontextprotocol.io/">MCP specification</a> · <a href="https://www.reso.org/data-dictionary/">RESO DD 2.0</a> </p> <p align="center"> <img src="https://img.shields.io/badge/TypeScript-3178C6?style=flat&logo=typescript&logoColor=white" alt="Built with TypeScript" /> <img src="https://img.shields.io/badge/Node.js-339933?style=flat&logo=nodedotjs&logoColor=white" alt="Requires Node.js 20+" /> <img src="https://img.shields.io/badge/MCP-000000?style=flat&logo=anthropic&logoColor=white" alt="Model Context Protocol" /> <img src="https://img.shields.io/badge/Claude.ai-D97706?style=flat&logo=anthropic&logoColor=white" alt="Claude.ai custom connector supported" /> <img src="https://img.shields.io/badge/Dust.tt-0F172A?style=flat&logoColor=white" alt="Dust.tt remote MCP supported" /> <img src="https://img.shields.io/badge/Qobrix_CRM-4A90D9?style=flat&logoColor=white" alt="Qobrix CRM integration" /> <img src="https://img.shields.io/badge/RESO_DD_2.0-1A1A2E?style=flat&logoColor=white" alt="RESO Data Dictionary 2.0" /> <img src="https://img.shields.io/badge/Zod-3E67B1?style=flat&logo=zod&logoColor=white" alt="Zod schema validation" /> <a href="https://github.com/gca-ltd/qobrix-crm-mcp/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue?style=flat" alt="Apache 2.0 license" /></a> </p>

---

Table of contents

• Installation Guide — Sharp Matrix intranet, pm2, Apache, Claude.ai + Dust.tt connectors
• User Guide — Mode A → Mode B → Mode C → Mode D (Claude.ai + Dust.tt) step-by-step
• What it does
• Who it is for
• Canonical real-estate workflows
• Tools at a glance
• Quick start
• Configuration
• Auth modes
• Enterprise OAuth
• Caching
• Cursor IDE setup
• Other MCP hosts
• Search expression syntax
• Fetching related data
• Testing
• Architecture
• How the LLM learns
• Technology
• License

---

What It Does

An AI assistant connected to this server can browse properties, qualify leads, track showings, review offers and contracts, audit follow-up activity, and discover CRM field schemas — all through natural language. Every tool description teaches the LLM which canonical real-estate workflow it belongs to, which RESO resource it maps to, and which tools to chain next.

Who it is for

• Brokerages & developers using Qobrix who want Claude.ai, Dust.tt, ChatGPT, or Cursor to answer questions grounded in live CRM data (not copy-pasted exports).
• Engineers wiring MCP into internal tools: stdio transport, typed Zod inputs, and no write surface — safe to experiment with prompts and agents.
• Data & operations teams running dashboards: use qobrix_count / qobrix_top_values for YoY-style metrics without custom scripts, and response caching to cut API load on repeat queries.
• Enterprise IT ready for per-agent identity: run Modes A/B from this package, then pair Mode C with SharpSir’s Enterprise OAuth (SSO) product when every user must authenticate as themselves — see Enterprise OAuth.

Canonical RE Workflows

The server is organized around six RESO-aligned business processes. The LLM receives these as built-in instructions so it can navigate the CRM without prior training.

| # | Workflow | RESO Mapping | Key Tools | |---|----------|-------------|-----------| | 1 | Listing Lifecycle | Property.StandardStatus | search_properties, get_property, list_media, get_property_coordinates | | 2 | Lead-Contact Lifecycle | Contacts.ContactType funnel | search_opportunities, get_contact, search_tasks | | 3 | Sales Pipeline | 8-stage buyer journey | get_leads_by_property, get_lead_properties, list_viewings, list_offers, list_contracts | | 4 | Showing / Viewing | ShowingAppointment | list_viewings, get_viewing, list_meetings | | 5 | Transaction / Offer | TransactionManagement | list_offers, get_offer, list_contracts, get_contract | | 6 | Activity / Follow-up | Engagement tracking | list_calls, list_meetings, list_email_messages, search_tasks |

Status Mappings

| Qobrix Property Status | RESO StandardStatus | |------------------------|---------------------| | available | Active | | reserved | Pending / Under Contract | | sold | Closed | | withdrawn | Withdrawn / Canceled |

| Qobrix Opportunity Status | RESO Lead Funnel | |--------------------------|------------------| | new | MQL / Raw Lead | | open | SQL / Active | | won | Closed Won | | closed_lost | Lost |

---

Tools at a Glance

64 tools — CRM entities, schema discovery, analytics (qobrix_count, qobrix_top_values, qobrix_top_records, qobrix_aggregate), a flexible deals shortcut (qobrix_deals), reporting (qobrix_timeseries, qobrix_funnel, qobrix_rep_scorecard, qobrix_stale_leads, qobrix_win_loss, qobrix_days_on_market), customer intelligence (qobrix_cohort), audit / change history (qobrix_get_changes, qobrix_search_changes, qobrix_field_change_history, qobrix_top_field_changers), cache helpers (qobrix_cache_stats, qobrix_cache_clear), and session & identity (qobrix_sign_in, qobrix_sign_out, qobrix_whoami):

| Entity Group | Tools | Capabilities | |-------------|-------|-------------| | Properties | 5 | List, Get, Search, Coordinates (map), Properties-by-Lead | | Contacts | 3 | List, Get, Search | | Agents | 3 | List, Get, Search | | Opportunities / Leads | 5 | List, Get, Search, Leads-by-Property, Lead-Properties | | Property Viewings | 3 | List, Get, Search | | Tasks | 3 | List, Get, Search | | Media | 2 | List (with entity filter), Get (with size variants) | | Projects | 4 | List, Get, Search, Coordinates | | Offers | 3 | List, Get, Search | | Contracts | 3 | List, Get, Search | | Calls | 2 | List, Get | | Meetings | 2 | List, Get | | Email Messages | 2 | List, Get | | Schema / Meta | 3 | Get Schema (field discovery), Get Field Options (enum values), Search DSL Help (full grammar + cheatsheets) | | Analytics | 4 | Counts, top-N field values, full-scan top-N records by numeric/date, and sum/avg/min/max/count aggregates (with single- or multi-dim grouping). Prefer list/search sort for a single page; use top_records/aggregate for full-set scans or nullable fields | | Deals | 1 | Flexible domain shortcut over the Contracts table (sales, rentals, listings, pipeline) with kind / contract_types[] / contract_statuses[] / date_field / min_price / party filters / summary block | | Reporting | 6 | Time-series with YoY (qobrix_timeseries), canonical sales funnel + conversion % (qobrix_funnel), per-rep scorecard / agent leaderboard (qobrix_rep_scorecard), silent-lead detection (qobrix_stale_leads), win-rate analytics (qobrix_win_loss), days-on-market (qobrix_days_on_market) | | Customers | 1 | Repeat-buyer / seller / lead cohorts (qobrix_cohort) — find contacts that appear on multiple closed deals or opportunities | | Audit | 4 | Per-record change log (qobrix_get_changes), cross-resource change search (qobrix_search_changes), field-level history (qobrix_field_change_history), top field changers (qobrix_top_field_changers) | | Cache | 2 | Stats and prefix or full invalidation for fresher reads | | Session & identity | 3 | Interactive sign-in (qobrix_sign_in), full revoke sign-out (qobrix_sign_out), current user profile (qobrix_whoami) — Mode C; sensible no-ops in Modes A/B |

Every tool description includes its canonical workflow role, RESO equivalent, verified include[] options, FK resolution guidance, and search expression examples.

Analytics & Deals usage examples

Server-side sort (OpenAPI sort[]) works for most fields — e.g. sort: "-list_selling_price_amount" on properties. Use qobrix_top_records / qobrix_aggregate when you need a full-dataset scan, or when a nullable field (e.g. opportunities.budget) returns no rows under server sort. "Closed deals" don't live as a property flag — they're rows in the Contracts table. The analytics/deals tools remove the need for client-side scripting:

// 1) Top 5 closed 2026 sales, sorted by final_selling_price_amount,
//    with property + agent + lawyers resolved to readable names.
{
  "tool": "qobrix_top_records",
  "args": {
    "resource": "contracts",
    "sort_by": "final_selling_price_amount",
    "search": "contract_type == \"cos\" and contract_status == \"agreed\" and date_of_contract >= \"2026-01-01\" and date_of_contract < \"2027-01-01\"",
    "top": 5
  }
}

// 2) 2026 sales volume, plus an agent leaderboard in one extra call.
{
  "tool": "qobrix_aggregate",
  "args": {
    "resource": "contracts",
    "field": "final_selling_price_amount",
    "op": "sum",
    "search": "contract_type == \"cos\" and contract_status == \"agreed\" and date_of_contract >= \"2026-01-01\" and date_of_contract < \"2027-01-01\"",
    "group_by": "commission_to_2",
    "top": 10
  }
}

// 3) Flexible "deals" shortcut — same answer as (1) with one default-laden call,
//    plus a full-set summary block (by_status, by_type, totals, median).
{ "tool": "qobrix_deals", "args": { "year": 2026, "top": 5 } }

// 4) Best 2026 rental contracts by final rental price.
{ "tool": "qobrix_deals", "args": { "kind": "rental", "year": 2026, "top": 5 } }

// 5) Under-contract reservations + closed sales together (pipeline + actuals).
{
  "tool": "qobrix_deals",
  "args": { "contract_statuses": ["reserved", "agreed"], "year": 2026 }
}

// 6) "My deals this year": uses the CURRENT_USER special var.
{
  "tool": "qobrix_deals",
  "args": { "assigned_to": "CURRENT_USER", "year": 2026 }
}

// 7) Monthly 2026 closed-sale volume with prior-year YoY %.
{
  "tool": "qobrix_timeseries",
  "args": {
    "resource": "contracts",
    "bucket": "month",
    "metric": "sum",
    "field": "final_selling_price_amount",
    "year": 2026,
    "search": "contract_type == \"cos\" and contract_status == \"agreed\"",
    "compare_to_prior": true
  }
}

// 8) Full 2026 sales funnel (Leads → Qualified → Viewing → Offer → Reserved → Closed).
{ "tool": "qobrix_funnel", "args": { "year": 2026 } }

// 9)