Metadata-Version: 2.4
Name: kamernet-mcp
Version: 0.1.0
Summary: MCP server for Kamernet.nl: search Dutch rooms, studios and apartments from Claude, Cursor, Codex and any AI agent
Project-URL: Homepage, https://github.com/jasp-nerd/kamernet-mcp
Project-URL: Repository, https://github.com/jasp-nerd/kamernet-mcp
Project-URL: Issues, https://github.com/jasp-nerd/kamernet-mcp/issues
Project-URL: Changelog, https://github.com/jasp-nerd/kamernet-mcp/releases
Author: jasp-nerd
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,apartments,claude,housing,kamernet,mcp,mcp-server,model context protocol,netherlands,rental,rooms
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: fastmcp<4,>=2.10
Requires-Dist: httpx>=0.27
Requires-Dist: platformdirs>=4.2
Requires-Dist: pydantic-settings>=2.3
Requires-Dist: pydantic>=2.7
Provides-Extra: auth
Requires-Dist: playwright>=1.45; extra == 'auth'
Description-Content-Type: text/markdown

<div align="center">

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="assets/banner-dark.svg">
  <img alt="kamernet-mcp: find Dutch rooms, studios and apartments from any AI agent" src="assets/banner-light.svg" width="800">
</picture>

**MCP server for [Kamernet.nl](https://kamernet.nl): search Dutch rooms, studios and apartments from Claude, Cursor, Codex and any AI agent.**

[![CI](https://github.com/jasp-nerd/kamernet-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/jasp-nerd/kamernet-mcp/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/kamernet-mcp)](https://pypi.org/project/kamernet-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/kamernet-mcp)](https://pypi.org/project/kamernet-mcp/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

**English** | [Nederlands](README.nl.md)

</div>

---

Finding a room in the Netherlands is brutal: good listings get 60+ replies within the hour. `kamernet-mcp` puts Kamernet, the largest Dutch platform for rooms, studios and apartments, inside your AI agent. The agent searches with your criteria, reads full listings in English and Dutch, ranks them against your budget, and tells you when something new appears.

```text
You:    Find me a furnished room in Utrecht under €900, at least 15 m², and rank
        the top 3 by value for a working professional who needs registration.

Agent:  → search_listings(city="Utrecht", max_rent=900, min_size=15, ...)
        → get_listing(...) ×3
        → score-listing prompt
        Here are the top 3, with deposits, energy labels and red flags…
```

## Quickstart

Requires [uv](https://docs.astral.sh/uv/) (or plain `pip`). One command:

```bash
claude mcp add kamernet -- uvx kamernet-mcp
```

Then ask Claude to find you a room. For other clients, use an install badge or unfold yours below.

[![Install in Cursor](https://img.shields.io/badge/Cursor-Install_kamernet--mcp-1a1a2e?style=for-the-badge)](https://cursor.com/en/install-mcp?name=kamernet&config=eyJjb21tYW5kIjogInV2eCIsICJhcmdzIjogWyJrYW1lcm5ldC1tY3AiXX0%3D)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_kamernet--mcp-0098FF?logo=visualstudiocode&logoColor=white&style=for-the-badge)](https://insiders.vscode.dev/redirect/mcp/install?name=kamernet&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22kamernet-mcp%22%5D%7D)

<details>
<summary><b>Claude Code</b></summary>

```bash
claude mcp add kamernet -- uvx kamernet-mcp
```

Or per project, committed to git, in `.mcp.json`:

```json
{
  "mcpServers": {
    "kamernet": { "command": "uvx", "args": ["kamernet-mcp"] }
  }
}
```

</details>

<details>
<summary><b>Claude Desktop</b></summary>

Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "kamernet": { "command": "uvx", "args": ["kamernet-mcp"] }
  }
}
```

</details>

<details>
<summary><b>Cursor</b></summary>

Use the install badge above, or add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):

```json
{
  "mcpServers": {
    "kamernet": { "command": "uvx", "args": ["kamernet-mcp"] }
  }
}
```

</details>

<details>
<summary><b>OpenAI Codex</b></summary>

```bash
codex mcp add kamernet -- uvx kamernet-mcp
```

Or add to `~/.codex/config.toml`:

```toml
[mcp_servers.kamernet]
command = "uvx"
args = ["kamernet-mcp"]
```

</details>

<details>
<summary><b>OpenCode</b></summary>

Add to `opencode.json` (note OpenCode uses an `mcp` key, not `mcpServers`):

```json
{
  "mcp": {
    "kamernet": {
      "type": "local",
      "command": ["uvx", "kamernet-mcp"],
      "enabled": true
    }
  }
}
```

</details>

<details>
<summary><b>VS Code (Copilot)</b></summary>

Use the install badge above, or add to `.vscode/mcp.json` (note VS Code uses a `servers` key):

```json
{
  "servers": {
    "kamernet": { "type": "stdio", "command": "uvx", "args": ["kamernet-mcp"] }
  }
}
```

</details>

<details>
<summary><b>Windsurf</b></summary>

Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "kamernet": { "command": "uvx", "args": ["kamernet-mcp"] }
  }
}
```

</details>

<details>
<summary><b>Gemini CLI</b></summary>

Add to `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "kamernet": { "command": "uvx", "args": ["kamernet-mcp"] }
  }
}
```

</details>

<details>
<summary><b>Zed</b></summary>

Add to Zed `settings.json`:

```json
{
  "context_servers": {
    "kamernet": { "command": { "path": "uvx", "args": ["kamernet-mcp"] } }
  }
}
```

</details>

<details>
<summary><b>Without uv (plain pip)</b></summary>

```bash
pip install kamernet-mcp
```

Then use `kamernet-mcp` as the command in any of the configs above.

</details>

## Tools

| Tool | What it does |
|---|---|
| `search_listings` | Search by city with filters: max rent (€), min size (m²), radius (km), property type (room / apartment / studio / anti-squat / student housing), sort order, pagination. |
| `get_listing` | Full details of one listing: bilingual description, rent + deposit, energy label, registration ("inschrijving") possibility, landlord stats (response rate, member since, verified badges), photos, coordinates. |
| `get_new_listings` | Stateless monitoring: "what appeared since my last check?" Lets your agent poll without hammering the site. |
| `account_status`* | Verify the configured Kamernet account can log in. |
| `reply_to_listing`* | **Experimental**: sends a reply to a landlord from your account, including Kamernet's applicant questions. |

\* Only registered when `KAMERNET_EMAIL` / `KAMERNET_PASSWORD` are set; see [Authenticated tools](#authenticated-tools-experimental).

There is also a `kamernet://filters` resource listing all valid filter values, and a `score-listing` prompt: a weighted rubric (price, location, quality, privacy, long-term fit) with bilingual deal-breaker detection ("no internationals" / "geen internationals") that your agent uses to rank listings for you.

## Configuration

Everything works with zero config. Optional environment variables:

| Variable | Default | Purpose |
|---|---|---|
| `KAMERNET_EMAIL` | — | Enables authenticated tools. |
| `KAMERNET_PASSWORD` | — | Enables authenticated tools. |
| `KAMERNET_REQUEST_DELAY` | `1.0` | Minimum seconds between requests to kamernet.nl. Values below 1.0 are ignored. |
| `KAMERNET_MAX_REPLIES_PER_SESSION` | `3` | Hard cap on automated replies per server session. |
| `KAMERNET_USER_AGENT` | transparent UA | Identifies this tool to Kamernet, with a link to this repo. |

## Authenticated tools (experimental)

Searching needs no account. **Replying to landlords requires a paid Kamernet premium account** (that's Kamernet's paywall, not ours) and browser automation:

```bash
uvx --with 'kamernet-mcp[auth]' kamernet-mcp   # or: pip install 'kamernet-mcp[auth]'
playwright install chromium
```

Set `KAMERNET_EMAIL` and `KAMERNET_PASSWORD` in your MCP client's `env` block. Cookies are cached locally so login happens rarely.

> [!WARNING]
> Automated replying violates Kamernet's terms of service and can get your account banned. Replies are hard-capped per session. Use it for messages you wrote and approved for one specific listing; a generic message sent to 50 landlords floods landlords and hurts your own chances. Use at your own risk.

## How it works

Kamernet is a Next.js site. Its CSS class names change on every deploy, which is what killed most earlier Kamernet bots. This server skips them and reads the structured `__NEXT_DATA__` JSON embedded in each public page: the same data the site renders from, and stable across frontend redesigns.

Politeness is enforced in code: a transparent User-Agent linking to this repo, a minimum 1-second delay between requests, no robots.txt-disallowed endpoints, and no tricks to evade rate limits. PRs that weaken this are rejected.

## Development

```bash
git clone https://github.com/jasp-nerd/kamernet-mcp
cd kamernet-mcp
uv sync --all-extras
uv run pytest          # 40+ tests, no network needed
uv run ruff check .
```

Tests run against sanitized snapshots of real Kamernet pages (`tests/fixtures/`) plus FastMCP's in-memory client, exercising the full MCP protocol without a browser or network. See [CONTRIBUTING.md](CONTRIBUTING.md).

Debug interactively with the MCP Inspector:

```bash
npx @modelcontextprotocol/inspector uv run kamernet-mcp
```

## Disclaimer

This is an unofficial, personal-use tool. It is **not affiliated with, endorsed by, or connected to Kamernet B.V.** in any way.

- Intended for **personal, non-commercial use** (finding yourself a home). Scraping personal data at scale can violate the GDPR/AVG; the Dutch DPA ([Autoriteit Persoonsgegevens](https://www.autoriteitpersoonsgegevens.nl/)) has published guidance on this. Don't harvest, republish or redistribute listing data.
- You are responsible for complying with [Kamernet's terms of service](https://kamernet.nl/en/terms-and-conditions) and applicable law.
- Listing data can be wrong or stale. Verify on kamernet.nl before you decide anything, and never pay a deposit before viewing the room.

## License

[MIT](LICENSE) © 2026 jasp-nerd

<!-- mcp-name: io.github.jasp-nerd/kamernet-mcp -->
