@marocain/mcp-server

@marocain/mcp-server

The official Model Context Protocol server for marocain.investments — bringing {GIN}, our authored real-estate intelligence for Morocco, into any MCP client (Claude Desktop, IDEs, agents).

What is {GIN}?

{GIN} is the platform's proprietary scoring DNA. Instead of one blurry "AI score", it speaks with two coherent pillars fused into one honest verdict:

• {GIN} Quality — how good the asset is (vision view/structural/condition + location + yield + WC2030 catalyst + trust).
• {GIN} Deal — how good the buy is (asking price vs. the M-Value AVM, adjusted for city momentum).
• Fused verdict — one buy/hold/pass headline that can never disagree with the numbers ("Prime asset, priced to buy", "Cheap — verify condition", …).

It's the difference between a good property and a good deal — the question generic scores never answer.

Install

No install needed — run it straight from npm:

npx -y @marocain/mcp-server

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "marocain": {
      "command": "npx",
      "args": ["-y", "@marocain/mcp-server"]
    }
  }
}

Tools

Tool	What it does
search_listings	Search AI-graded Moroccan listings by city, typology, price, rooms, free-text.
get_listing	Full detail for one listing — price, AI scores, M-Value, trust, provenance, {GIN} pillars.
get_gin_score	The {GIN} verdict: Quality + Deal pillars + the fused buy/hold/pass headline.
get_market	Macro market facts for a city or national scope (median price, supply, momentum, catalysts).
listing_derive	AI-derived one-paragraph investment memo for a listing.

Example response shapes

search_listings({ city: "Marrakech", limit: 1 }) →

{
  "count": 1,
  "total": 1947,
  "limit": 1,
  "items": [{
    "id": "34da0a53-...",
    "url": "https://marocain.investments/listing/34da0a53-...",
    "title": "PALAIS D'EXCEPTION À VENDRE – MARRAKECH",
    "city": "Marrakech",
    "district": "Route de Fès",
    "typology": "villa",
    "price_usd": 9630000,
    "rooms": 6, "surface_m2": 3200
  }]
}

get_gin_score({ id }) → the authored verdict:

{
  "id": "…",
  "title": "…",
  "price_usd": 9630000,
  "gin_verdict": { "key": "prime_value", "label": "Prime asset, priced to buy", "tone": "strong" },
  "gin_quality": 76,
  "gin_deal": 64,
  "m_value_usd": 9100000,
  "trust": { "title_verified": false, "fcr_status": "unknown" }
}

Troubleshooting

Symptom	Cause	Fix
request timed out after 30000ms	Upstream slow or unreachable.	Retry. Bump MAROCAIN_TIMEOUT_MS if your network is high-latency.
The Marocain API returned an error (403)	Rare — Vercel platform-level anti-bot on very bursty traffic.	Back off and retry. Public reads are uncached at the moment.
The Marocain API returned an error (4xx/5xx)	Upstream issue.	Retry; report if persistent. The full status code is in the server's stderr.
ignoring disallowed MAROCAIN_API_BASE	You set MAROCAIN_API_BASE to a non-HTTPS or non-allowlisted host.	Leave it unset (the default is correct) or use https://marocain.investments.

Moat-safe by design

No tool ever returns an agent's phone number or private contact details. The public API hides them, and buyer enquiries are routed only through the platform's own lead flow on the site. You can discover, score and analyse inventory freely — contact happens on-platform.

Configuration

Env var	Default	Purpose
MAROCAIN_API_BASE	https://marocain.investments	Override the API origin (testing).

Related

• Skills catalog: @hei33enberg/luxury-skills (npm) — the full machine-readable capability catalog this server draws from.
• Live API: https://marocain.investments/api/public/*.

Releasing

# from the repo root, after edits + green tests
npm version patch              # or minor / major
npm publish --access public    # needs an npm token in .npmrc (gitignored)
git push --follow-tags

License

MIT © marocain.investments