Qobrix CRM MCP Server

Table of contents

• What it does

• Who it is for

• Canonical real-estate workflows

• Tools at a glance

• Quick start

• Configuration

• 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 ChatGPT, Claude, 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.

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.

Status Mappings

Tools at a Glance

56 read-only 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), and cache helpers (qobrix_cache_stats, qobrix_cache_clear):

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

Analytics & Deals usage examples

The Qobrix REST API silently ignores sort on some calculated/nullable numeric fields (notably contracts.final_selling_price_amount and opportunities.budget), and "closed deals" don't actually live as a single property flag — they're rows in the Contracts table. The three new 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) 2026 agent leaderboard by volume (omit `user` for leaderboard mode).
{ "tool": "qobrix_rep_scorecard", "args": { "year": 2026, "sort_by": "volume", "top": 10 } }

// 10) Silent leads — open opportunities with no activity in 30 days.
{ "tool": "qobrix_stale_leads", "args": { "since_days": 30 } }

// 11) Multi-dim pivot: 2026 closed-sale volume by city × property_type.
{
  "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": ["property_id", "contract_type"],
    "top": 10
  }
}

// 12) Repeat buyers — contacts behind 2+ closed sales in 2026.
{ "tool": "qobrix_cohort", "args": { "kind": "buyers", "year": 2026, "min_count": 2 } }

// 13) Win-rate by lead source in 2026, with top loss reasons resolved.
{
  "tool": "qobrix_win_loss",
  "args": { "year": 2026, "group_by": "source", "include_top_losses": true }
}

// 14) 2026 days-on-market by property type, with longest/shortest outliers.
{
  "tool": "qobrix_days_on_market",
  "args": { "kind": "sold", "year": 2026, "group_by": "property_type", "include_outliers": true }
}

Quick Start

git clone https://github.com/sharpsir-group/qobrix-crm-mcp.git
cd qobrix-crm-mcp
npm install
npm run build

Configuration

Create a .env file in the project root:

QOBRIX_API_URL=https://yourcrm.qobrix.com
QOBRIX_API_USER=your-api-user-uuid
QOBRIX_API_KEY=your-api-key
QOBRIX_LOCALE=en-US          # optional

Caching

All MCP tools are read-only GETs, so a response cache cannot corrupt CRM state. The server wraps one chokepoint (QobrixClient.request()) with a read-through cache, so every existing tool benefits without any contract change.

Design — cache-aside with single-flight coalescing:

• Tier 1 — in-memory LRU (always on, zero deps): per-process, TTL'd, size-capped.

• Tier 2 — Redis (optional, lazy-loaded via dynamic import()): set QOBRIX_REDIS_URL to enable; the server falls back to memory-only on any Redis error.

• Single-flight: when the LLM fires parallel tool calls that hit the same cold cache key (common with qobrix_top_values), all in-process callers share one upstream fetch.

• Errors are never cached — a transient 5xx will not get stuck.

• TTL only, no stale-while-revalidate in v1.

Environment variables:

Cache tools (exposed to the LLM):

Recommended Redis server config (for a dedicated cache-only Redis, per Redis docs):

maxmemory 256mb
maxmemory-policy allkeys-lru
maxmemory-samples 10

TTL guidance — Redis docs recommend short TTLs for frequently-changing data (60–120s) and longer for stable data (hours). 300s is a conservative default for a CRM that mixes lead pipeline (changes minutely) with property listings (changes hourly). Use qobrix_cache_clear when you need an instant refresh.

Trade-off / known limit: Single-flight coalescing is in-process only. Multi-instance deployments behind one shared Redis can still see modest stampede on cold keys; a distributed SETNX lock is future work and not needed for single-user MCP clients.

Best-practices alignment:

Cursor IDE setup

This server uses stdio MCP (a local node process). Cursor discovers servers from project or user mcp.json: .cursor/mcp.json inside the folder you opened, or ~/.cursor/mcp.json for all workspaces.

1. Prerequisites

• Node.js 20+ on the machine where Cursor runs the MCP (local laptop or remote SSH host).

• Clone this repo, install, and build (see Quick Start).

• dist/index.js must exist (npm run build) before adding the MCP entry.

2. Credentials

1. Copy the template: cp .env.example .env

2. Edit .env and set at least QOBRIX_API_URL, QOBRIX_API_USER, and QOBRIX_API_KEY (see Configuration).

3. Keep .env out of git; it is listed in .gitignore.

3. Where to put the JSON

Merge your entry into the existing "mcpServers" object; do not replace the whole file if you already have other servers.

4. Recommended: node --env-file (Node 20+)

Pass absolute paths so it works the same whether the workspace root is this repo or a parent folder (and so SSH remote paths resolve correctly).

{
  "mcpServers": {
    "qobrix-crm-mcp": {
      "command": "node",
      "args": [
        "--env-file=/absolute/path/to/qobrix-crm-mcp/.env",
        "/absolute/path/to/qobrix-crm-mcp/dist/index.js"
      ],
      "description": "Read-only Qobrix CRM MCP"
    }
  }
}

Why this pattern:

• Credentials stay in .env, not in JSON.

• Node loads the file before your server starts, so process.env is populated even when the host’s envFile field is ignored or behaves inconsistently for stdio servers.

5. Alternative: inline env

Useful if you cannot use --env-file (older Node). Secrets live in mcp.json — restrict file permissions and do not commit them.

{
  "mcpServers": {
    "qobrix-crm-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/qobrix-crm-mcp/dist/index.js"],
      "env": {
        "QOBRIX_API_URL": "https://yourcrm.qobrix.com",
        "QOBRIX_API_USER": "your-api-user-uuid",
        "QOBRIX_API_KEY": "your-api-key",
        "QOBRIX_LOCALE": "en-US"
      }
    }
  }
}

You can also use Cursor’s config interpolation (for example ${env:QOBRIX_API_KEY}) so values are injected from your OS environment instead of literals.

6. Optional: envFile in MCP JSON

Cursor supports an envFile property for stdio servers. Some setups do not pass those variables into the child process reliably; if tools fail with “Missing required environment variables”, switch to --env-file as in step 4.

7. After editing mcp.json or .env

1. Reload MCP — Command Palette → MCP restart, or reload the Cursor window.

2. Check logs — View → Output → pick “MCP” / “MCP Logs” in the dropdown; fix path or Node errors there.

3. Tool approval — By default Cursor asks before each tool call; you can allow auto-run for trusted tools in Cursor settings if you prefer.

Other MCP hosts

Claude Desktop — same stdio shape: command + args to node and either --env-file or env in the host’s MCP config file.

CI / headless — run node --env-file=.env dist/index.js with a stdio MCP client library; ensure .env is supplied via secrets, not committed.

Search Expression Syntax

Tools that accept a search parameter use Qobrix's expression language:

Tip: Call qobrix_get_schema with any resource name to discover all available field names before building search expressions.

Fetching Related Data

Three strategies to resolve foreign keys:

1. include[] parameter — expand associations inline in one call

qobrix_get_property({ id: "...", include: ["Agents", "PropertyViewings"] })

2. Separate get call — take the UUID from an FK field and call the appropriate tool

// property.agent → UUID
qobrix_get_agent({ id: "<agent-uuid>" })

3. Search by FK — find related records via search expression

qobrix_search_properties({ search: 'agent == "<agent-uuid>"' })

Only include[] values marked Verified in tool descriptions are guaranteed to work. When include[] is unavailable for an association, use search-by-FK.

Payload defaults

To keep tool outputs short enough for the calling LLM's context window, list / search / get tools default to compact payloads:

Override per call only when the caller actually needs the heavier payload:

// Cheap browse — recommended for most reporting / pipeline calls
qobrix_list_properties({ limit: 10 });

// Heavy detail — only when the LLM truly needs nested FKs + media URLs
qobrix_list_properties({ limit: 5, expand: true, media: true });

// Prefer surgical include[] over full expand=true:
qobrix_get_property({ id: "...", include: ["AgentAgents", "ProjectProjects"] });

This change typically shrinks qobrix_list_properties({ limit: 10 }) from ~300 KB to ~5–10 KB.

Output cap

Every tool result is capped at QOBRIX_MCP_MAX_RESULT_CHARS characters of rendered JSON (default 30 000, roughly 7.5 K tokens). Behaviour:

• Paginated payloads ({ data: [...], pagination: {...} }): truncated to the largest prefix of data[] that fits, and a _truncated block is attached with kept_rows, omitted_rows, original_chars, max_chars, and a hint telling the LLM how to scope the next call.

• Non-paginated payloads (single get, custom analytic shapes): the JSON is clipped at the cap and a QOBRIX_MCP TRUNCATED trailer is appended with the same guidance.

Override the cap with the env var (set to 0 to disable, not recommended in production):

QOBRIX_MCP_MAX_RESULT_CHARS=60000

If you regularly hit the cap, that's a signal to use fields[] (whitelist columns), a tighter search expression, a smaller limit, or keep expand=false / media=false.

Testing

The project includes 172 automated tests across 48 describe suites (integration, multi-step scenarios, RESO workflows, cache, and output-cap behaviour):

# Integration tests — individual tool mechanics
npm test

# Scenario tests — multi-step tool chains (18 real-world scenarios)
npm run test:scenarios

# Workflow tests — canonical RE business processes (8 RESO-aligned suites)
npm run test:workflows

# Cache tests — read-through, single-flight, LRU eviction (no API needed)
npm run test:cache

# Format tests — output cap + truncation behaviour (no API needed)
npm run test:format

# Run everything
npm run test:all

Architecture

src/
├── index.ts          # MCP server entry point + RESO workflow instructions
├── client.ts         # QobrixClient — HTTP + read-through response cache
├── cache.ts          # LRU memory tier, optional Redis, single-flight coalescing
├── types.ts          # TypeScript interfaces
├── schemas.ts        # Zod schemas with rich LLM-facing descriptions
└── tools/
    ├── index.ts      # Tool registration hub
    ├── properties.ts # Listing Lifecycle tools
    ├── contacts.ts   # Lead-Contact Lifecycle tools
    ├── agents.ts     # RESO Member tools
    ├── opportunities.ts # Sales Pipeline tools
    ├── viewings.ts   # Showing Lifecycle tools
    ├── tasks.ts      # Follow-up & Pipeline Management tools
    ├── media.ts      # Media Lifecycle tools
    ├── projects.ts   # Project/Development tools
    ├── offers.ts     # Transaction Lifecycle tools
    ├── contracts.ts  # Transaction close tools
    ├── activities.ts # Activity Tracking (calls, meetings, emails)
    ├── analytics.ts  # qobrix_count, qobrix_top_values, qobrix_top_records, qobrix_aggregate
    ├── deals.ts      # qobrix_deals (flexible Contracts shortcut)
    ├── reports.ts    # qobrix_timeseries (bucketed metric + YoY), qobrix_days_on_market
    ├── pipeline.ts   # qobrix_funnel, qobrix_stale_leads, qobrix_win_loss
    ├── productivity.ts # qobrix_rep_scorecard
    ├── customers.ts  # qobrix_cohort (repeat buyers/sellers/leads)
    ├── cache.ts      # qobrix_cache_stats, qobrix_cache_clear
    └── meta.ts       # Schema Discovery tools
test-suite/
├── integration.test.mjs  # 55 integration tests
├── scenarios.test.mjs    # 54 scenario tests
├── workflows.test.mjs    # 39 workflow tests
└── cache.test.mjs        # 19 cache unit tests

How the LLM Learns

The server teaches the LLM at three levels:

1. Server instructions — top-level instructions field in the MCP initialize response provides the full data model, six canonical workflows with tool recipes, search syntax, FK resolution strategies, and known quirks.

2. Tool descriptions — each of the 46 tool descriptions includes its canonical workflow role, RESO equivalent, verified include[] options, FK field mappings, response shape, and search examples.

3. Parameter descriptions — Zod schemas provide per-parameter help with concrete examples, valid enum values, and cross-tool references.

Technology

License

Apache License 2.0 — Copyright 2025–2026 SharpSir Group