Skip to main content
Glama
Sign In
flatfind

flatfind

by AyushRajSinghParihar
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

flatfind — codex-style CLI for Bangalore house hunting (NoBroker)

flatfind takes NoBroker's real API, wraps phone+OTP login, lets you describe what you want in plain English ("2bhk in koramangala under 30k"), searches automatically, and scores photos GOOD/AVERAGE/BAD with whatever vision model you have (Claude / OpenAI / Gemini / offline heuristic).

Built to be driven by humans in a terminal AND by agents (Claude Code / Codex / OpenCode) via --json + a zero-dep MCP server.

Install

From PyPI (once published — see below):

pipx install flatfind        # recommended: isolated CLI install
# or
pip install flatfind
# or run without installing:
uvx flatfind search "2bhk in koramangala under 30k"

From source:

git clone https://github.com/ayushrajsinghparihar/flatfind.git
cd flatfind
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
# or: pip install -e ".[dev]"

Related MCP server: Apartment Hunter MCP Server

60-second tour

flatfind localities
flatfind search "2bhk in koramangala under 30k" --limit 10
flatfind show 8aa99668 --json
flatfind analyze 8aa99668
flatfind probe-params --locality koramangala   # what the API accepts/rejects

Auth (phone + OTP — real NoBroker flow)

Search works without login. Login unlocks owner contact numbers.

flatfind auth send-otp --phone 98765XXXXX
flatfind auth login --phone 98765XXXXX --otp 123456
flatfind auth status
flatfind auth logout

Endpoints (reverse-engineered, see docs/REVERSE_ENGINEERING.md):

step

method + endpoint

params

send OTP

POST /api/v2/account/otp/send

phone (+opt otpAPP)

login

POST /api/v1/account/login/otp (fallback /api/v2/user/login/otp)

phone, otp

search

GET /api/v3/multi/property/RENT/filter

searchParam (base64 localities), city, pageNo, radius, rent, bhk, buildingType, orderBy, ...

photos

https://images.nobroker.in/images/<id>/<file>

from photos[].imagesMap

Photo analysis — depends on YOUR model

env present

backend

quality

ANTHROPIC_API_KEY

Claude Sonnet vision

best

OPENAI_API_KEY

GPT-4o-mini vision

cheap + good

GEMINI_API_KEY / GOOGLE_API_KEY

Gemini Flash vision

good

none

offline heuristic (count/resolution/owner-upload/metadata)

honest filter

flatfind analyze <id> --model auto      # default: best available
flatfind analyze <id> --model heuristic # force offline

Use from Claude Code / Codex / OpenCode

Option A — CLI: agents just run the commands above with --json. Full playbook in skills/SKILL.md (drop it into your agent's skills dir).

Option B — MCP server (zero extra deps):

// .mcp.json (Claude Code) — adapt for Codex/OpenCode
{ "mcpServers": { "flatfind": { "command": "flatfind", "args": ["mcp"] } } }

Tools: search_flats, show_flat, analyze_flat, auth_status, probe_params.

Two-layer rule: analyze filters, the host agent re-reads top photo URLs with its own eyes and makes the final call.

Repo layout

src/flatfind/
  cli.py               Typer CLI (search/show/analyze/auth/probe/mcp)
  config.py            paths, endpoints, session store
  nobroker/
    auth.py            send_otp / login_with_otp / status
    search.py          searchParam builder + paginated search
    probe.py           accepts-vs-rejects param prober
    detail.py          photo URL builder + summarizer
    localities.py      bundled Bangalore lat/lon table
    client.py          session + headers + cookie persistence
  agent/
    planner.py         NL -> filters (offline regex, reproducible)
    scorer.py          vision (claude/openai/gemini) + heuristic fallback
  mcp/server.py        dependency-free MCP over stdio
skills/SKILL.md        agent playbook
docs/REVERSE_ENGINEERING.md  how the API was mapped
tests/                 offline unit tests (no network)

Dev

python -m pytest -q
flatfind search "2bhk in hsr layout under 28k" --limit 5 --json | head -50

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    This server cannot be deployed

    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers