Metadata-Version: 2.5
Name: realnymetr-mcp
Version: 0.3.1
Summary: MCP server for RealnyMetr (realnymetr.pl) — query Polish real-estate analytics (listings, recorded sale prices, rents, valuations, forecasts) from Claude and other agents.
Project-URL: Homepage, https://realnymetr.pl
Project-URL: Documentation, https://realnymetr.pl/subscription
Project-URL: Changelog, https://realnymetr.pl/updates
License: MIT License
        
        Copyright (c) 2026 RealnyMetr (realnymetr.pl)
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: claude,mcp,model-context-protocol,poland,property,real-estate
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.2.0
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
Requires-Dist: pytest>=8; extra == 'test'
Requires-Dist: respx>=0.21; extra == 'test'
Description-Content-Type: text/markdown

# RealnyMetr — MCP server

<!-- mcp-name: pl.realnymetr/realnymetr-mcp -->

Query the RealnyMetr platform's (realnymetr.pl) Polish real-estate analytics directly from
Claude (or any MCP client): listing search, underpriced-anomaly and best-deal
detection, comparable district averages, city stats, per-listing price history and
forecasts, rent estimates and seasonal (holiday-let) yields.

Requests are authenticated with a personal API key; every signed-in account may create
one (a free account's key is a trial of 100 requests a month, the Pro subscription gives
500 a day, the Business plan 30,000 a month — see Limits below).

## 1. Get an API key

1. Sign in on the platform (a free account is enough for the trial volume; the Pro
   subscription or the Business plan for more).
2. Open **Subscription → API keys**, create a key, and copy it — it is shown **once**
   (it starts with `rm_`).

## 2. Install

The server speaks MCP over **stdio**, so a client starts it as a local process. Two
packages, the same tools and the same names — pick whichever runtime your client
already has.

```bash
# Python ≥ 3.10
pipx install realnymetr-mcp          # or: pip install realnymetr-mcp
# or run it without installing:
uvx realnymetr-mcp

# Node ≥ 18
npx -y realnymetr-mcp                # no install step
```

`npx`/`uvx` are the usual choice in a client config: nothing to install, and the client
always starts the current version.

## 3. Configure your MCP client

Everything below is the same server with the same key. Replace the key with your own;
`REALNYMETR_API_KEY` is the only required setting.

### Claude Desktop

`claude_desktop_config.json` (macOS `~/Library/Application Support/Claude/`,
Windows `%APPDATA%\Claude\`):

```json
{
  "mcpServers": {
    "realnymetr": {
      "command": "npx",
      "args": ["-y", "realnymetr-mcp"],
      "env": { "REALNYMETR_API_KEY": "your_key_here" }
    }
  }
}
```

Python instead of Node: `"command": "uvx", "args": ["realnymetr-mcp"]`. Restart the
client; the **realnymetr** tools appear in the tools menu.

### Claude Code

```bash
claude mcp add realnymetr --env REALNYMETR_API_KEY=your_key_here -- npx -y realnymetr-mcp
```

Add `--scope project` to write it into the repository's `.mcp.json` so your team shares
it, or `--scope user` for every project on your machine.

### VS Code (GitHub Copilot, agent mode)

`.vscode/mcp.json` in the workspace, or the user-level settings. **VS Code's key is
`servers`, not `mcpServers`** — a config copied from Claude will silently do nothing.
Its `inputs` prompt keeps the key out of the file:

```json
{
  "inputs": [
    { "id": "realnymetr-key", "type": "promptString",
      "description": "RealnyMetr API key", "password": true }
  ],
  "servers": {
    "realnymetr": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "realnymetr-mcp"],
      "env": { "REALNYMETR_API_KEY": "${input:realnymetr-key}" }
    }
  }
}
```

Open the Chat view, switch to **Agent** mode, and the tools appear under the tools
picker.

### Cursor

`~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (one project):

```json
{
  "mcpServers": {
    "realnymetr": {
      "command": "npx",
      "args": ["-y", "realnymetr-mcp"],
      "env": { "REALNYMETR_API_KEY": "your_key_here" }
    }
  }
}
```

Windsurf, Zed, Cline and most other editors use this same `mcpServers` shape.

### OpenAI Agents SDK (your own agent, in code)

```python
from agents import Agent, Runner
from agents.mcp import MCPServerStdio

async def main():
    async with MCPServerStdio(
        params={"command": "npx", "args": ["-y", "realnymetr-mcp"],
                "env": {"REALNYMETR_API_KEY": "your_key_here"}},
    ) as realnymetr:
        agent = Agent(
            name="Property analyst",
            instructions="Use RealnyMetr for Polish property data. Recorded sale "
                         "prices come from the national register; asking prices do not.",
            mcp_servers=[realnymetr],
        )
        print((await Runner.run(agent, "What did flats in Kraków Krowodrza actually "
                                       "sell for last quarter?")).final_output)
```

The TypeScript SDK's `MCPServerStdio` takes the same `command`/`args`/`env`.

### Codex CLI (OpenAI)

```bash
codex mcp add realnymetr --env REALNYMETR_API_KEY=your_key_here -- npx -y realnymetr-mcp
```

or by hand in `~/.codex/config.toml`:

```toml
[mcp_servers.realnymetr]
command = "npx"
args = ["-y", "realnymetr-mcp"]
env = { REALNYMETR_API_KEY = "your_key_here" }
```

### GitHub Copilot in JetBrains, Eclipse, Xcode

The same `servers` JSON as VS Code above, pasted into Copilot's MCP settings
(JetBrains: Copilot → Settings → MCP). Agent mode must be on.

### ChatGPT (connectors / developer mode)

**Not yet.** A ChatGPT connector must be a server ChatGPT can reach over HTTPS, and this
package is a local stdio process, so it cannot be added there as it stands — the same
holds for the Responses API's hosted `mcp` tool. A hosted HTTP endpoint for the same
tools is on the roadmap; until then, use ChatGPT's models through the Agents SDK or
Codex above, which do run local servers.

### Anything else

Any MCP client that can start a command works:

```
command: npx     args: ["-y", "realnymetr-mcp"]      (Node ≥ 18)
command: uvx     args: ["realnymetr-mcp"]            (Python ≥ 3.10)
env:     REALNYMETR_API_KEY=<your key>
```

### Environment variables

| Var | Required | Default | Purpose |
|-----|----------|---------|---------|
| `REALNYMETR_API_KEY` | yes | — | Your account's API key |
| `REALNYMETR_API_BASE` | no | `https://realnymetr.pl/api` | Point at staging or a self-hosted API |
| `REALNYMETR_CA_BUNDLE` | no | — | A CA bundle, for a corporate TLS-inspecting proxy |
| `REALNYMETR_TLS_VERIFY` | no | `1` | `0` disables certificate checks — last resort |

The older `PPA_*` names are still read: the package was called `ppa-mcp` until
2026-10-16, and a config written then keeps working.

## 4. Tools

74 tools, in nine groups.

### Listings and the asking market

| Tool | What it returns |
|------|-----------------|
| `search_listings` | Active listings by city/type/price/area/rooms/building year/street/district, within `radius_m` of a point, or inside a polygon (`area="lng,lat;…"`); `full_ownership_only` leaves out shares, TBS, co-op rights, non-residential units and auctions |
| `area_stats` | Price figures for a polygon you define: asking PLN/m² (median, middle half, by rooms), median price and size, how many listings sit on an exact point, and the register's sold PLN/m² inside the same area over 24 months |
| `investment_scan` | Listings around a point ranked by value against a size-matched benchmark, with gross rental yield |
| `investment_shortlist` | A ranked buy-to-let shortlist for an area: listings by exact point or by a street the register places there, budget incl. a garage, full ownership only, finishing cost, cohort rent, cash flow per down payment, break-even price, negotiation positions for the top rows |
| `get_listing` | Full detail for one listing id |
| `find_listing_by_url` | The tracked listing behind a portal URL (resolves cross-portal copies) |
| `listing_sources` | The portals `find_listing_by_url` accepts |
| `find_rental_by_url` | The tracked rental behind a portal URL (eight rental portals) |
| `listing_also_listed_on` | The same flat on other portals, each pairing re-checked before it is returned |
| `listing_price_history` | A listing's recorded ask-price changes |
| `listing_forecast` | Per-listing quarterly forecast (regional trend + own history; paid plans) |
| `listing_segment_forecast` | Six months ahead for one listing from its segment's deed index (district, market, size band), with its place in the queue |
| `find_anomalies` | Under/overpriced listings vs their district per-type average, each with its gap to what similar flats SOLD for (`sold_gap_pct`) |
| `best_deals` | Best-value listings ranked by deal quality, each with its gap to what similar flats SOLD for; only listings seen within 7 days |
| `district_average` | Comparable-cohort average price/m² (opt. by area band) |
| `district_prices` | Every district of a town with its asking PLN/m² (median by default) and listing count, for the filters given |
| `city_stats` | Headline market stats for a city |
| `category_prices` | Asking prices per category in a town: flats by market in full ownership, houses and commercial per m², plots per m² of land, garages per space — count, median, mean |
| `price_index` | Historical price-index series for a city |
| `locate_address` | A street and house number as the building's point (from the sale register); with `street_fallback`, an unknown building lands on its street |
| `suggest_address` | The platform's address autocomplete: streets as typed, then a street's buildings with their points (register first, our exact listings for new buildings) |
| `purchase_costs` | Notary, PCC and court fees of buying at a price, itemised with their legal basis |

### One listing: what to offer, how long it lasts

| Tool | What it returns |
|------|-----------------|
| `listing_negotiation` | What to offer for one listing, and the evidence behind the number |
| `listing_negotiation_brief` | Opening / target / walk-away for one listing from four readings — sales on the same street (last 3 months first), the comparables' valuation, the same with delisted flats, the delisted flats' last asks — plus the price at which the rent covers a mortgage, and what to ask for besides the price |
| `refresh_listing` | Read one listing's own page now — description, legal form (share / TBS / auction / non-residential / land-register area), condition, the portal's listing date — so the brief and cash-flow tools answer on current facts (rationed: 1 per listing per 10 min, a daily cap) |
| `listing_time_to_sell` | How long comparable listings stayed up, and where this one sits |
| `listings_that_went` | The comparable listings behind `listing_time_to_sell`, quickest first |
| `listing_condition` | Is it ready to let? Description, finishing standard, flags, photos and a first-pass reading with its evidence |
| `listing_cashflow` | Rental cashflow with mortgage scenarios (optional garage, finishing budget, rent growth) — the Cashflow page's arithmetic |
| `mortgage_rates` | NBP reference rate, a typical margin and the mortgage-rate estimate the cashflow tools use |

### Market movement, time on market, location

| Tool | What it returns |
|------|-----------------|
| `price_movers` | The biggest price drops (or rises) among active listings in the last N days, ranked by the size of the move |
| `recent_price_changes` | The newest recorded price changes, the raw feed behind `price_movers` |
| `days_on_market` | How long listings stay up before they leave the market, with a per-city / type / market breakdown |
| `sea_view_premium` | What a sea view adds to the asking price per m², town by town on the coast |
| `affordability` | Salaries against prices: the county's average gross wage (GUS), m² per salary, years of pay for 50 m², and the series against the register's medians |
| `town_demography` | Who lives in a town and whether people are arriving: population and its change since 2020, the young and retired shares, net migration per 1,000 (GUS) |
| `listing_location_quality` | The nearest transit, shops, food, schools and health care to a listing, and a 0-100 location score |
| `valuation_sold_comparables` | One of your valuations against what comparable flats actually sold for (the register), beside the asking-price value |

### Rents

| Tool | What it returns |
|------|-----------------|
| `rent_estimate` | Measured rent for a city/district/type; pass `area` for the size-band cohort |
| `rent_by_district` | Every district's measured rent for one city, with per-size-band figures |
| `area_band_yields` | Which size of flat pays best in a town: per m² band the median asking PLN/m², the median rent per m², the gross and the net yield, and the best band |
| `rent_index` | The monthly rent series for a cohort (collected since September 2026) |
| `rent_history` | Our monthly city/district rents with gross yield, beside Poland's rent index (since 2010) and its 1/3/5-year growth |
| `custom_index` | Your own index over time, as the History page builds it: asking prices per m² (any district / type / market / area), rents from our rental listings (`basis="rent"`), or the register's medians for the same cohort — a district's deeds as the index (`basis="sold"`) |
| `custom_index_forecast` | Forecast that custom index — AutoARIMA from 8 points, a labelled trend from 4; weekly series forecast in weeks |
| `rent_comparables` | The individual rentals behind a cohort rent — the sample, not another median |
| `seasonal_rental` | Holiday-let seasonal yield (coastal/resort towns) |

### Forecasts

| Tool | What it returns |
|------|-----------------|
| `market_forecast` | A city's quarterly forecast on asking prices, sold prices or rents (rent: Poland's index at the city's rent level, with annual growth) |

### Towns, districts and the RealnyMetr index (public aggregates, every plan)

| Tool | What it returns |
|------|-----------------|
| `list_towns` | Every town with public figures: slug, flats on sale, asking and sold medians, rent, yield |
| `town_overview` | One town in one call: asking median and its change, sold medians of the newest settled quarter, rent, yield, a district table, wages and demography |
| `district_overview` | One district: asking median and its gap to the town, the register's sold median over 24 months, rent, yield, a per-room table |
| `realnymetr_index` | The monthly median DEED price per m² of a town's flats per segment (market, size band) over up to 60 months, with a 12-month forecast and the CPI for real prices |
| `register_overview` | A town's sold prices in brief: quarterly deed medians over 24 months and the newest settled quarter per market |

### Your valuations (write to your own account only)

| Tool | What it does |
|------|--------------|
| `valuate_listing` | Value a tracked listing from comparables, and keep the valuation |
| `create_valuation` | Value any property; street + number place it on the map by themselves. `ownership_form` states the legal form (a share, TBS or co-op tenancy gets the full-ownership value with a note, never a discount); `latest.adjustments` lists every adjustment applied, with the measured floor / building-year / legal-form effects |
| `list_valuations` / `get_valuation` | Your saved valuations; `accuracy_hints` names what would sharpen one |
| `update_valuation` | Change inputs, including the cohort switches (same street, nearby + radius, off-market) |
| `revalue` | Recompute against today's listings |
| `valuation_history` / `valuation_comparables` | How the value moved; the comparables behind it |
| `valuation_forecast` | Six months ahead for a valuation (asking or deed basis) from its segment's index |
| `valuation_report` | Issue a PDF report of a valuation (value, selling price, how it was built, register sales, listings, market, rent and yields, a map); `email=True` mails the PDF to your confirmed address |
| `valuation_reports` | A valuation's PDF reports and their status |
| `delete_valuation` | Permanently delete a valuation and its history |

### Account

| Tool | What it returns |
|------|-----------------|
| `account_usage` | Your plan, its limits, what is used and left, when it resets — and what the plan reaches |
| `service_status` | Whether the site takes new accounts (open / beta) and the expected launch |

### Sold prices — what was actually paid

Most tools above are built from **asking** prices. These six (with `realnymetr_index` and
`register_overview`) are built from deeds in the
national price register (RCN, GUGiK), which is the only source here that says what buyers
actually paid. Free to reuse since 13 February 2026, under the 26 September 2025 amendment to *Prawo geodezyjne i
kartograficzne* — attribute it when you quote figures.

| Tool | What it answers |
|---|---|
| `sold_prices` | Recorded sales, newest first; `matched_only=True` adds the asking price and the signed gap |
| `sold_price_stats` | Count, median price, median PLN/m², and the period actually covered |
| `negotiation_room` | How far below asking a cohort really sells — the buyer's question |
| `sold_price_map` | Sales aggregated onto a grid, for "where does it trade above X?" |
| `sold_price_trend` | Quarterly median PLN/m² — a price history made of deeds |
| `market_liquidity` | How much actually changes hands, by district — deed counts, not prices |

Two cautions worth passing on to whoever reads the answer:

- **The register lags.** A deed reaches it weeks after signing, and only ingested cities
  are present. Call `sold_price_stats` first and look at `count` and the covered period
  before treating a number as a market reading.
- **`negotiation_room` returns two different measures.** The cohort gap has large samples
  but is exposed to composition; the matched pairs are exact but sparse. Both come with
  sample sizes, and `confidence` states the weight outright. Quote the sample size.

### Example prompts

- "Find the 10 most underpriced 2–3 room apartments in Gdańsk under 800k."
- "What's the comparable price per m² for Kraków / Dębniki apartments, 50–60 m²?"
- "Show the price history and forecast for listing 12345."
- "Estimate the gross rental yield for a 55 m² flat in Wrocław centre."
- "What did 40–60 m² flats actually sell for in Podgórze last year, and how much below
  asking? I have cash."
- "Which parts of Wrocław trade above 12,000 zł/m² on recorded sales?"

## Notes

### Searching by place, not district

`search_listings` accepts `near="<lat>,<lng>"` with `radius_m` (default 1000, max 50000)
to find listings within a real distance of a point — use it whenever the user names a
place rather than a district, since district boundaries are administrative and often
kilometres wide.

**Coordinates are not all real.** When a listing arrives without coordinates the platform
scatters a point across its district so it still appears on the map. Addresses with a
house number are geocoded to their building over time, but a large share of active
listings still carries such a fabricated position, and until you filter them out a
radius search returns flats whose addresses are nowhere near the target. Every result
exposes `location_is_exact` (`true` / `false` / `null` = unknown); pass
`location_exact=True` to keep only geocoded ones.

`investment_scan` does the whole buy-side workflow in one call: search around a point,
compare each result to a **size-matched** local benchmark, and attach a gross rental
yield from measured district rents. It excludes approximate coordinates by default.
Yields are gross — before czynsz, tax, voids and management.

- **Most tools are read-only.** The exceptions are the valuation tools
  (`valuate_listing`, `create_valuation`, `update_valuation`, `delete_valuation`,
  `revalue`, `valuation_report`, `delete_valuation_report`), which write
  to **your own account only** — an API key belongs to one user and every valuation
  query is scoped to that user, so one subscriber can never read or change another's.
  `delete_valuation` is permanent and takes its estimate history with it.
- Nothing else writes: listings, prices and market data are never modified.
- A tool argument can only ever be the path segment or the query value it was meant to
  be: both packages percent-encode it whole, so `../admin` or `a/b?x=1` reaches no other
  endpoint.
- Every signed-in account may create a key; the volume follows the account's plan:
  **free** 100 requests a month (a trial, up to 2 keys), **Pro** 500 a day (up to 5
  keys), **Business** 30,000 a month and 1,000 a day (up to 10 keys), plus a per-minute
  burst (20 / 60 / 180). Limits are counted per account, reset at midnight and on the
  first of the month (Europe/Warsaw). Past a limit a tool answers
  `api_quota_exhausted` with the plan, the limit and `resets_at`; `account_usage` shows
  what is left. What a plan REACHES: every plan reads listings, the public aggregates
  (towns, districts, the RealnyMetr index, rents, wages, demography) and the sold-price
  statistics, trend and map; a free account has once a month each a saved valuation, a
  forecast, a custom index and a per-flat forecast (then `perk_exhausted` with
  `resets_at`); the deed list and `negotiation_room`, the priced rankings, `investment_shortlist`,
  page refreshes and PDF reports are the paid plans' (a free key answers 403 with the
  reason). What the plans cost is on the site's current price list
  (realnymetr.pl/subscription, also served by the API) — this package quotes no prices.
- A refusal is passed on as the server wrote it: `code` (`api_quota_exhausted`,
  `api_burst`, `perk_exhausted`, `subscription_required`, `already_today`…), the limit
  and `resets_at`. A heavy sold-price view the server is still preparing (503
  `preparing`) is waited for, up to 45 seconds, before the tool says to call again.
- Revoke a key any time from **Subscription → API keys**; a revoked key stops working
  immediately.
