# finn-eiendom-mcp

> **Private, self-hosted property analysis platform for Norwegian real estate.** Analyzes FINN listings, enriches with Eiendom.no estimates, scores against personal preferences, and surfaces bargain candidates, hybel potential, renovation upside, and risk flags. Exposed through an MCP server, a CLI, and a Python library — all sharing one service layer.

This is a **personal tool**. Not a SaaS, not a crawler, not legal/financial advice. Run locally, low frequency, your own data.

---

## What it does

```
FINN search URL  →  ranked shortlist of homes
                   with reasons, risks, comps, broker questions
```

Specifically:

* Parses FINN search and listing pages.
* Resolves each listing to an Eiendom.no `unitCode` for valuation and similar-units.
* Builds a `unit_vector` and fetches recently-sold comparables.
* Scores 9 components (economy, market position, comps, location, layout, outdoor, hybel, renovation, risk).
* Classifies as *bargain*, *safe*, *hybel*, *renovation*, *lifestyle*, or *risk*.
* Caches everything in SQLite; remembers what you've liked or rejected.
* Detects new / removed / changed listings between runs.

---

## Three ways to use it

| Surface         | When you want…                                                 | Entry point             |
| --------------- | -------------------------------------------------------------- | ----------------------- |
| **CLI**         | Quick triage in a terminal, scripting, cron                    | `finn-eiendom ...`      |
| **MCP server**  | Claude Desktop, n8n, AI agents — conversational analysis       | `finn-eiendom-mcp`      |
| **Python lib**  | Tests, notebooks, custom scripts                               | `import finn_eiendom`   |

All three call the same underlying `service.py` — same defaults, same semantics, same results.

---

## Quick start

### Requirements

* Python **3.12+**
* `uv` (recommended) or `pip`

### Install

```bash
git clone <your-repo-url> finn-mcp
cd finn-mcp

uv venv                              # or: python3.12 -m venv .venv
source .venv/bin/activate
uv pip install -e ".[dev]"           # or: pip install -e ".[dev]"
```

### First run (CLI)

```bash
# Triage a FINN search
finn-eiendom analyze-search 'https://www.finn.no/realestate/homes/search.html?location=...' --format table

# Drill into one listing
finn-eiendom get-ad 462400360 --format markdown

# Mark a listing as liked
finn-eiendom save-feedback 462400360 liked --notes "great layout, check fellesgjeld"

# Find similar properties to liked listings
finn-eiendom similar-to-liked 462400360
```

### First run (Claude Desktop)

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent on Linux:

```json
{
  "mcpServers": {
    "finn-eiendom": {
      "command": "/absolute/path/to/finn-mcp/.venv/bin/finn-eiendom-mcp",
      "env": {
        "FINN_CACHE_PATH": "/absolute/path/to/finn-mcp/data/finn.sqlite",
        "EIENDOM_NO_ENABLED": "true"
      }
    }
  }
}
```

Restart Claude Desktop. Then in any chat:

> Analyze this FINN search and shortlist the top 5 for a couple in Oslo with a 9–12 MNOK budget, willing to renovate, prefer hybel potential:
> `https://www.finn.no/realestate/homes/search.html?location=...`

For deep usage — every command, every MCP tool, every env var — see [`USAGE.md`](USAGE.md).

---

## Architecture in one screen

```
       CLI (typer)        MCP server (FastMCP)         ← thin, parallel front ends
            \                  /
             \                /
              service.py                                ← cache + fetch orchestration
                   ↓
              analysis.py                               ← shortlist + summary
                   ↓
         search / ad / eiendom_no / scoring / feedback
                   ↓
              parser / http / cache (SQLite)
                   ↓
              FINN HTML + Eiendom.no JSON
```

`formatting.py` lives next to `service.py` and is shared by both CLI and MCP for JSON / markdown / table rendering.

**Key rule:** CLI and MCP are siblings. They never call each other. Both call the same `service.py` functions. See [`PRD.md`](PRD.md) §17 for the full code-ownership constitution.

---

## Project documents

Read in this order depending on what you're doing:

| If you want to…                       | Read                                                |
| ------------------------------------- | --------------------------------------------------- |
| Use the tool                          | This README, then [`USAGE.md`](USAGE.md)            |
| Understand the design                 | [`PRD.md`](PRD.md), especially §1, §12, §17         |
| Contribute / extend / hack on it      | [`AGENTS.md`](AGENTS.md), then [`PROJECT.md`](PROJECT.md), then `.github/instructions/*.md` |
| Run the cleanup pass on the repo      | [`CLEANUP.md`](CLEANUP.md)                          |
| Build out unfinished features         | [`IMPLEMENTATION.md`](IMPLEMENTATION.md)            |

---

## Status

* **Phase 0 (spike):** done.
* **Phase 1 (core MVP):** mostly done.
* **Phase 2 (MCP + CLI):** in progress — driven by [`IMPLEMENTATION.md`](IMPLEMENTATION.md).
* **Phase 3+ (scoring v2, agent workflows, dashboard):** future.

---

## Safety and compliance

* Private, low-frequency, user-triggered use only. No public deployment.
* Configurable request delays (`FINN_REQUEST_DELAY_SECONDS`, `EIENDOM_NO_REQUEST_DELAY_SECONDS`) — defaults are conservative.
* Aggressive caching to minimize external requests.
* No bypassing of rate limits, bot protection, authentication, or access controls.
* No public redistribution of FINN or Eiendom.no data.
* Scores, estimates, and comparable sales are **decision support, not advice**. Don't substitute this for a real broker, lawyer, or technical inspector.

---

## License / use

Personal project. Not for redistribution. Don't expose the MCP HTTP transport on a public interface — keep it on LAN, Tailscale, or behind auth.