deweloperuch-mcp

<p align="center"><img src="https://raw.githubusercontent.com/MBratkowski/deweloperuch-mcp/main/assets/icon.svg" alt="deweloperuch-mcp icon" width="160"></p>

<h1 align="center">deweloperuch-mcp</h1>

<p align="center">
  <a href="https://github.com/MBratkowski/deweloperuch-mcp/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/MBratkowski/deweloperuch-mcp/ci.yml?branch=main&label=CI" alt="CI"></a>
  <a href="https://github.com/MBratkowski/deweloperuch-mcp/releases/latest"><img src="https://img.shields.io/github/v/release/MBratkowski/deweloperuch-mcp" alt="Latest release"></a>
  <a href="https://pypi.org/project/deweloperuch-mcp/"><img src="https://img.shields.io/pypi/v/deweloperuch-mcp" alt="PyPI version"></a>
  <a href="https://pypi.org/project/deweloperuch-mcp/"><img src="https://img.shields.io/pypi/pyversions/deweloperuch-mcp" alt="Python versions"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License: MIT"></a>
</p>

<!-- mcp-name: io.github.MBratkowski/deweloperuch-mcp -->

Ask an AI assistant about new-build apartments in Poland: asking prices with their history, real transaction prices and official statistics.

An unofficial [MCP](https://modelcontextprotocol.io) server and command-line tool over the public data of [deweloperuch.pl](https://deweloperuch.pl): developers' asking prices (with price history), transaction prices from the Real Estate Price Register (RCN) and statistics of GUS and NBP. Thirteen read-only tools, usable from an MCP client such as Claude Desktop or Claude Code, or from the `deweloperuch` CLI.

> **Disclaimer.** This is an independent project. It is **not affiliated with, endorsed by or sponsored by** deweloperuch.pl, GUS, NBP or the Register's publishers. The authors of deweloperuch.pl have agreed to the project's use of their service; the client identifies itself as `deweloperuch-mcp/<version>` with a link to this repository.
>
> - It is **read-only**: it never creates or changes anything on the service.
> - It is a **polite client**: at most 1 request per second, one at a time, shared by all processes on your machine; responses are cached; after a 401, 403, 429 or a captcha/WAF challenge it stops sending requests until you clear the lock yourself.
> - **Please respect the service.** It is run by other people; ask narrow questions and do not build loops or bulk downloads on top of this tool.
> - Data accuracy is not guaranteed. Prices are asking or registered prices, not valuations or advice.
> - You are responsible for how you use the tool and the data, including the terms of the service.

## What you can ask

- *Buying a flat:* "Find flats of 40–55 m² in Kraków's Podgórze up to 800 000 PLN, cheapest per m² first." (The service has no filter by number of rooms; filter by area instead.)
- *Judging an offer's price:* "Is this offer a good deal? Show its price history, the lowest price of the last 30 and 90 days, and whether the reduction looks suspicious."
- *Checking a developer:* "What does this developer build, and how many offers are active in which cities?"
- *Market and transaction prices:* "How do asking prices in Gdańsk compare with registered transaction prices over the last quarters?"
- *Valuation:* "Roughly what is a 55 m² flat at this address worth, based on nearby transactions?"
- *Comparing cities:* "Rank cities by transaction price per m², and show wages and unemployment next to them."

## Install

Pick the first option that fits you; they go from no terminal to expert. Supported systems: macOS and Linux. **Windows is not supported** (the shared request limiter uses `fcntl` file locks).

### 1. Claude Desktop, no terminal

1. Download `deweloperuch-mcp-<version>.mcpb` from the [latest release](https://github.com/MBratkowski/deweloperuch-mcp/releases/latest).
2. Double-click it, or drag it into Claude Desktop → Settings → Extensions → Install, then restart Claude Desktop.

You get: the 13 tools and 4 prompts in Claude Desktop. The extension uses the `uv` runtime (`server.type` is `uv` in its manifest), so the first start fetches Python and the dependencies and takes about a minute; you install nothing yourself. It has no command-line tool; if the server is ever stopped (STOP), see [lifting a STOP without a checkout](docs/configuration.md#lifting-a-stop-without-a-checkout).

### 2. Any MCP client, with uv

You get: the same tools in Claude Desktop, Claude Code or any client that starts a stdio server. Nothing to clone.

Install [uv](https://docs.astral.sh/uv/) once (macOS and Linux):

```
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Claude Code:**

```
claude mcp add deweloperuch -- uvx deweloperuch-mcp
```

**Claude Desktop** (`claude_desktop_config.json`; other clients use the same `command` and `args`):

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

To run straight from GitHub instead of PyPI, use `uvx --from git+https://github.com/MBratkowski/deweloperuch-mcp@v0.1.2 deweloperuch-mcp` (`@v0.1.2` pins the release; drop it to follow `main`). `pip install deweloperuch-mcp` works too.

### 3. Agent skill for the CLI

You get: an AI coding agent that knows how to use the `deweloperuch` CLI (which command to call, how to read the output, what to do on STOP), without an MCP server. The skill is called `deweloperuch-cli`; a new agent session loads it by itself.

```
npx skills add MBratkowski/deweloperuch-mcp
```

This uses the [skills](https://github.com/vercel-labs/skills) CLI (needs Node.js) and works with any agent it supports; you choose the agent. Without Node.js:

```
uvx --from deweloperuch-mcp deweloperuch skill install
```

It writes to `~/.claude/skills/deweloperuch-cli` (Claude Code, for the user). Options: `--project` (this project's `./.claude/skills`), `--agent codex|cursor|gemini-cli|github-copilot`, `--dir PATH` (writes `PATH/deweloperuch-cli`), `--force` (replace a different copy; without it a changed copy is never overwritten, and the installer never writes through symlinks). `deweloperuch skill show` prints the skill, `deweloperuch skill path` its folder. Details: [docs/cli/commands/skill.md](docs/cli/commands/skill.md).

Claude Code plugin marketplace:

```
/plugin marketplace add MBratkowski/deweloperuch-mcp
/plugin install deweloperuch@deweloperuch-mcp
```

### 4. The CLI on its own

You get: the `deweloperuch` command for your terminal and scripts; see [docs/cli/README.md](docs/cli/README.md).

```
uvx --from deweloperuch-mcp deweloperuch --help    # one-off, nothing installed
uv tool install deweloperuch-mcp                   # installs deweloperuch and deweloperuch-mcp
deweloperuch locations search krak
```

### 5. From source (contributors)

Requirements: Python 3.11 or newer and [uv](https://docs.astral.sh/uv/).

```
git clone https://github.com/MBratkowski/deweloperuch-mcp.git
cd deweloperuch-mcp
uv sync
uv run deweloperuch --help                  # sends no requests
```

As the client command use `uv run --directory /path/to/deweloperuch-mcp deweloperuch-mcp` (Claude Code: `claude mcp add deweloperuch -- uv run --directory /path/to/deweloperuch-mcp deweloperuch-mcp`). More: [CONTRIBUTING.md](CONTRIBUTING.md) and [docs/mcp/README.md](docs/mcp/README.md#mcp-client-configuration).

### Troubleshooting

- **`uvx: command not found` or `spawn uvx ENOENT`**: install uv (option 2). Claude Desktop may not see your shell `PATH`, so put the full path from `which uvx` in `command`.
- **The server does not appear in Claude Desktop**: quit and restart Claude Desktop after installing the extension or editing the config.
- **Windows**: not supported; use macOS or Linux.
- **STOP / exit code 3**: after a 401, 403, 429 or a captcha/WAF challenge the client stops sending requests in every process, so as not to burden the service. A **429** expires by itself after the pause (at least 60 s). The other causes last until **you** lift them, after checking the cause (`deweloperuch stop status` shows the state; an AI agent must not lift it). The MCP server stays halted until you restart it. Details and the command: [docs/configuration.md](docs/configuration.md#stop-shared-lock-between-processes).
- **Where is the cache?** Responses are cached in memory only. The limiter lock and the STOP record live in `~/.cache/deweloperuch-mcp` (`$XDG_CACHE_HOME/deweloperuch-mcp`). Do not delete that directory: it would also lift a STOP.

## Tools

Overview, argument rules, errors and result sizes: [docs/mcp/README.md](docs/mcp/README.md).

| Tool | Description |
|---|---|
| [`search_locations`](docs/mcp/tools/search_locations.md) | Finds cities, districts and streets by a name fragment and returns `city_slug`. |
| [`search_offers`](docs/mcp/tools/search_offers.md) | A page of developers' apartment offers in a city or the whole of Poland, with price, area, price-per-m², district, status and price-drop filters and sorting. |
| [`get_offer`](docs/mcp/tools/get_offer.md) | One offer with its full price history and price flags (lowest price in 30/90 days, suspicious reduction). |
| [`search_investments`](docs/mcp/tools/search_investments.md) | Investments of a city (averages, sorting, filter by developer) or by name across Poland. |
| [`get_investment`](docs/mcp/tools/get_investment.md) | An investment with its developer, average prices and a list of offers. |
| [`search_developers`](docs/mcp/tools/search_developers.md) | Finds developers by a name fragment and returns `developer_slug`. |
| [`get_developer`](docs/mcp/tools/get_developer.md) | A developer profile: summary, investments with active offers and cities. |
| [`get_market_statistics`](docs/mcp/tools/get_market_statistics.md) | Offer-market statistics of one city: counts, price, price per m² and area distributions, the largest developers. |
| [`get_transaction_statistics`](docs/mcp/tools/get_transaction_statistics.md) | Transaction prices (RCN) of a city by m