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
- Sign in on the platform (a free account is enough for the trial volume; the Pro subscription or the Business plan for more).
- 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_statsfirst and look atcountand the covered period before treating a number as a market reading. negotiation_roomreturns 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, andconfidencestates 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_valuationis 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
../adminora/b?x=1reaches 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_exhaustedwith the plan, the limit andresets_at;account_usageshows 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 (thenperk_exhaustedwithresets_at); the deed list andnegotiation_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 andresets_at. A heavy sold-price view the server is still preparing (503preparing) 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.