Apartment Hunter MCP Server
Provides local persistent storage for apartment listings, profiles, notifications, and price history using SQLite.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Apartment Hunter MCP Server Find new apartments matching my saved profile"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Apartment Hunter
Legal Disclaimer: This is a private automation tool for personal use only. By using this software, you agree to the Legal Disclaimer and Fair Use Policy.
Apartment Hunter is a powerful aggregator and search platform for rental apartments. It automates finding, filtering, and scoring housing options without manually checking websites every hour. Currently, the system only supports data from krisha.kz, but the architecture allows for easy extension. It supports precise polygon-based geographic search, semantic text search (RAG), and LLM-powered quality scoring.
Quick Start
# 1. Start the MCP server for Codex Desktop / Claude
uv run apartment-hunter-mcp
# 2. Or run the data ingestion pipeline manually
uv run apartment-hunter-ingestAI Skills
The project includes specialized AI skills in .agents/skills to enhance your AI assistant:
apartment-search: Domain workflow for apartment search, ingestion, monitoring, and translating listing jargon.
city-district-context-kz: Provides context on Kazakhstan cities and districts (transport, pricing, livability).
html-report-generator: Generates a visual HTML report of apartments with photos and links, and launches it on localhost.
How to use skills: You don't need to manually install these skills. Simply open this project folder using your favorite AI CLI (like Antigravity CLI / Codex CLI) and the agent will automatically discover and load the skills from the local workspace.
Related MCP server: @striderlabs/mcp-airbnb
Use Cases
Agents / MCP: Connect it to Codex Desktop to chat with your apartment database ("Show me 2-bedroom apartments near Megapark under 500k, sort by newest").
Precise Geography: Stop relying on inaccurate text search. Draw a polygon on a map, pass the coordinates, and only get apartments strictly within that exact boundary.
AI Scoring: Automatically rate apartments out of 10 based on renovation quality, furniture condition, and specific user preferences using Vision LLMs.
Market Monitoring: Run ingestion periodically (e.g. via cron) to track price drops and immediately catch new listings before they are rented out.
Architecture Philosophy
This is a Library-First project. The core logic is built as a reusable, source-agnostic Python library. All site-specific scraping and adapters are isolated plugins, ensuring the core remains stable and extensible.
License
Available Tools
15 toolsanalyze_apartmentA
Run LLM analysis on a specific apartment.
Scores the apartment 0-10 based on price/quality ratio, condition, location, and other factors. Returns score, pros, cons, and summary. Forces re-analysis even if already analyzed.
Inputs: source_id (required). Returns: result
compare_apartmentsA
Compare 2-5 apartments side by side.
Provide a list of source_ids to compare their key characteristics.
Inputs: source_ids (required). Returns: result
create_search_profileB
Create a search profile for ongoing apartment monitoring.
The profile defines filters and preferences. The ingestion pipeline will use these profiles to fetch new apartments and send notifications.
Inputs: name (required), city, rooms, sources, +12 more. Returns: result
delete_search_profileC
Delete a search profile by ID.
Inputs: profile_id (required). Returns: result
download_apartment_photosA
Download apartment photos locally so the AI agent can inspect them.
Returns the absolute paths of the downloaded images. You (the AI) can then
use your view_file tool on these paths to visually analyze the apartment.
Inputs: source_id (required), limit. Returns: result
get_apartment_detailsA
Get full details for a specific apartment by its source_id (e.g. 'krisha:1013405508').
Returns all available fields including LLM analysis, price history, and photos.
Inputs: source_id (required). Returns: result
get_new_apartmentsA
Get apartments discovered in the last N hours (default: 24).
Shows the most recent apartments sorted by score.
Inputs: since_hours. Returns: result
get_price_historyC
Get price change history for an apartment.
Inputs: source_id (required). Returns: result
get_statsA
Get statistics about the apartment database.
Shows total apartments, new apartments, analyzed count, average prices, scores, etc.
Inputs: no named parameters. Returns: result
get_top_apartmentsA
Get top-rated apartments sorted by LLM score.
Returns the highest-scored apartments, optionally filtered by city, rooms, or price. Only returns apartments that have been analyzed.
Inputs: city, limit, rooms, price_max. Returns: result
list_search_profilesA
List all active search profiles.
Inputs: no named parameters. Returns: result
run_ingestionA
Run the data ingestion pipeline.
Fetches new apartments from all sources for the specified profile (or all active profiles if none specified), analyzes them, and sends notifications. This may take several minutes depending on the number of pages to scrape.
Inputs: profile_id. Returns: result
search_apartmentsA
Search apartments by structured filters.
Returns a list of apartments matching the given criteria. Use this for precise filtering by price, rooms, area, district, etc. For free-text queries like 'cozy apartment near park', use semantic_search instead.
Inputs: city, rooms, area_max, area_min, +5 more. Returns: result
search_by_profileA
Show apartments matching a search profile, ranked by semantic similarity.
Uses the profile's hard filters (price, rooms, polygon) AND the nl_description for semantic re-ranking via ChromaDB vector search. Pass hours=0 to return all stored apartments for this profile (no time filter).
Inputs: profile_id (required), hours, limit. Returns: result
semantic_searchB
Search apartments by natural language query using semantic/vector search.
Examples: 'уютная квартира с видом на горы рядом с метро', 'большая квартира с евроремонтом в центре'. Optionally filter by city, max price, or room count.
Inputs: query (required), city, rooms, n_results, +1 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Most tools have distinct purposes, but `semantic_search` and `search_apartments` could be confused without reading descriptions. Also `analyze_apartment` and `get_apartment_details` overlap slightly.
The majority follow a clear verb_noun pattern in snake_case. `semantic_search` is the main deviation, being adjective_noun, but it still reads naturally.
With 15 tools, the server covers all major apartment hunting workflows (discovery, analysis, monitoring, comparison) without being overwhelming.
Core operations like search, details, analysis, and profile management are covered. Missing an update search profile tool is a minor gap, but the set handles the primary use cases.
Maintenance
Related MCP Connectors
MCP server giving Claude AI access to 22+ NYC public-record databases for real estate due diligence
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Hosted Web Crawler MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
MCP server for real-estate agents: listings, CRM, German market data and AI media tools.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server for Stessa rental-property accounting platform, enabling AI agents to query properties, portfolios, banking, documents, and tenancies via natural language.MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for Airbnb — lets AI agents search listings, check availability, manage reservations, and book stays via browser automation.14 npmMIT
- AlicenseAqualityDmaintenanceMCP server exposing portfolio AI tools including semantic search, evaluation framework, and prompt management, enabling natural language interaction with these services via Claude Desktop.5ISC
- FlicenseNot gradedqualityDmaintenanceA production-grade MCP server enabling Claude to perform comprehensive NJ real estate workflows including property search, valuation, neighborhood intelligence, investment analysis, and agent tools via 20 tools and 15+ data sources.-