Content
# Hemnet MCP
[](https://github.com/chrischall/hemnet-mcp/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/hemnet-mcp)
[](LICENSE)
An [MCP](https://modelcontextprotocol.io) server for **[hemnet.se](https://www.hemnet.se)**,
Sweden's largest real-estate portal. Search for-sale listings, look up
sold prices (*slutpriser*), pull full listing detail and photos, compute
market statistics, resolve addresses, and run a Swedish mortgage
calculation — all from Claude.
> ⚠️ This project is **built and maintained by AI (Claude)**. It reads
> hemnet.se through its public GraphQL API. Use at your own discretion
> and within hemnet.se's terms of service.
## Highlights
- **No configuration.** Hemnet serves its read queries anonymously — no
login, no API key, no browser extension. `npx hemnet-mcp` just works.
- **Sold prices (slutpriser).** Hemnet's signature dataset: achieved
final price, asking price, and over/under-asking percentage — the comps
an agent needs to value a home.
- **Swedish-native.** Money in SEK, areas in m², rooms, `bostadsrätt`
fees (avgift), energy class, and a mortgage model that follows Swedish
rules (amorteringskrav, ränteavdrag).
- **Embeddable.** Ships as a standalone MCP server *and* as a library so
it can be composed into a larger multi-portal server.
## Install
### Claude Code / Claude Desktop (npx)
```json
{
"mcpServers": {
"hemnet": {
"command": "npx",
"args": ["-y", "hemnet-mcp"]
}
}
}
```
### From source
```bash
git clone https://github.com/chrischall/hemnet-mcp
cd hemnet-mcp
npm install
npm run build
node dist/index.js
```
## Tools
| Tool | What it does |
| --- | --- |
| `hemnet_autocomplete_location` | Resolve a place name (`"Vasastan"`) to Hemnet location ids — the starting point for search. |
| `hemnet_search_listings` | Search active for-sale listings by location + filters (price SEK, rooms, m², property type, keywords). |
| `hemnet_get_listing` | Full detail for one listing (price, fee, running costs, m², rooms, tenure, energy class, broker, description, photos). |
| `hemnet_get_listing_photos` | Just the gallery photo URLs. |
| `hemnet_search_sold` | Search **sold** listings with final price, asking price, and over/under-asking %. |
| `hemnet_get_sold_listing` | Full detail for one sold listing. |
| `hemnet_get_market_stats` | Median/average final price and price-per-m² for a location. |
| `hemnet_compare_listings` | Fetch several listings at once for side-by-side comparison. |
| `hemnet_get_by_address` | Resolve a free-text street address to a live listing. |
| `hemnet_calculate_mortgage` | Local Swedish monthly-cost calculator (interest + amortisation + fee, gross & after-tax). No network. |
| `hemnet_healthcheck` | Verify the Hemnet GraphQL endpoint is reachable. |
### Example flow
```
1. hemnet_autocomplete_location { query: "Vasastan" }
→ location_id 925970
2. hemnet_search_listings { location_ids: ["925970"], rooms_min: 2, price_max: 6000000 }
→ listing summaries
3. hemnet_get_market_stats { location_ids: ["925970"], housing_form_groups: ["APARTMENTS"] }
→ median final price, price-per-m²
4. hemnet_calculate_mortgage { price: 4695000, interest_rate: 3.9, monthly_fee: 2800 }
→ monthly cost, gross and after-tax
```
Or pass a free-text `location` to any search tool and it resolves the top
hit for you.
## Money & units
All output records use **numbers**: `price` / `final_price` /
`fee_monthly` in SEK, `living_area_sqm` / `land_area_sqm` in m², `rooms`
as a number. A derived `price_per_sqm` is always included when price and
living area allow it (even when Hemnet omits it, common on houses). The
original Hemnet-formatted strings are kept alongside as `*_formatted`.
## Library use
hemnet-mcp is also importable, so it can serve as a Hemnet *portal
source* inside a larger project (e.g. a cross-portal realty
orchestrator):
```ts
import { createHemnetClient, computeMarketStats } from 'hemnet-mcp';
const hemnet = createHemnetClient();
const { cards } = await hemnet.searchSales({ locationIds: ['925970'] }, { limit: 50 });
const stats = computeMarketStats(cards.map(formatSaleCard));
```
The library entry (`import … from 'hemnet-mcp'`) re-exports the client,
the normalised record types, the pure derivations
(`computeMarketStats`, `calculateSwedishMortgage`, money/url helpers),
and every tool registrar (`registerHemnetTools(server, client)` to graft
the tools onto your own MCP server).
## Development
```bash
npm test # vitest (mocked transport, no network)
npm run test:coverage # 100% coverage enforced on src/**
npm run typecheck
npm run build
```
Tests drive every tool and the client through an in-memory fake
transport — no live hemnet.se calls. See `CLAUDE.md` for architecture,
the GraphQL quirks, and contribution conventions.
## License
MIT
