Skip to main content

RealnyMetr — MCP server

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.

# 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\):

{
  "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

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:

{
  "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):

{
  "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)

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)

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

or by hand in ~/.codex/config.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.

Metadata

Release files for realnymetr-mcp 0.3.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for realnymetr-mcp 0.3.1
File Size Uploaded Provenance Actions
realnymetr_mcp-0.3.1.tar.gz 104.6 kB Without provenance Details for realnymetr_mcp-0.3.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for realnymetr-mcp 0.3.1
File Interpreter ABI Platform Actions
realnymetr_mcp-0.3.1-py3-none-any.whl Python 3 none any Details for realnymetr_mcp-0.3.1-py3-none-any.whl

Total release size: 155.5 kB

Release files / realnymetr_mcp-0.3.1.tar.gz

Download URL realnymetr_mcp-0.3.1.tar.gz
Size 104.6 kB
Tags Source
SHA-256 checksum
How to use checksums
5411f50f275b17bcccaf94f8650637fe202c801c85ad04830b34c6099cb2cd73
BLAKE2b-256 checksum
How to use checksums
7ee906be34a33611b4006986b7bfb4282a0a8f4b6333b15e3584aefb569b3266
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Release files / realnymetr_mcp-0.3.1-py3-none-any.whl

Download URL realnymetr_mcp-0.3.1-py3-none-any.whl
Size 50.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e3068a27b75828d5e74920636a7e4f6516997a0e5affc05595a580b959b9b07c
BLAKE2b-256 checksum
How to use checksums
179e51b3d2ad648760049104635ecb0843b0cd3c39329e90df8dcc36fd1acf65
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Security for realnymetr-mcp 0.3.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.3.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page