cityparity: Cost-of-Living & Quality-of-Life Comparison
About
cityparity gives AI agents real cost-of-living and quality-of-life comparison tools. Point it at two cities and it returns take-home pay, a full cost breakdown (housing, healthcare, childcare, food, transit, travel home, property tax), and the equivalent salary you'd need in the
Details
- Author
- summerstateofmind
- Downloads
- 322
- Categories
- Other
Jump to
- Compare two cities with full cost breakdown and equivalent salary
- Discover supported city slugs grouped by country
- Get one-city profile with tax shape and headline costs
- Rank cities by composite quality score with custom filters
- Retrieve safety-net values (parental leave, vacation, healthcare) for up to 20 cities
- Access inbound tax regime details for expat-friendly schemes
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
cityparity: Cost-of-Living & Quality-of-Life ComparisonCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Configure any Streamable HTTP–capable MCP client to point at https://mcp.cityparity.com/mcp. For stdio-only clients, use the npm bridge package cityparity-mcp (install globally or via npx). Start by calling list_cities to discover supported city slugs, then use tools like compare_cities, rank_cities, or get_safety_net as needed.
compare_cities
Compare two cities for one household: take-home pay, full cost breakdown, the equivalent target salary needed to match source net cash, non-cash lifestyle deltas (vacation, parental leave, healthcare), and a 0-100 quality score on five weighted dimensions. Use this for a head-to-head between two named cities; for a single city call get_city_summary, and to rank many cities call rank_cities. Read-only, no side effects; returns a text summary plus structured JSON. RSU income is NOT a parameter; RSU is treated as source-only because grants typically do not follow you across employers.
list_cities
List all city slugs supported by cityparity, grouped by country. Call this first to discover valid slugs before any other tool; the optional country filter narrows to one country. Read-only, no side effects; returns a text summary plus structured JSON.
get_city_summary
Concise profile of one city: currency, tax shape (bracket count + top rate + payroll/national insurance), headline costs (rent / groceries / transit / childcare), safety-net values (parental leave, vacation, universal healthcare), and data freshness. Lighter than compare_cities; use when the user is asking about one place rather than a comparison. On parental leave, quote safety_net.parental_leave_summary rather than building your own sentence: some countries (Ireland, Australia, the UK, Czechia, part of Sweden) pay a flat weekly cash sum instead of a share of salary, so parental_leave_paid_pct is 0 or partial for them and stating it alone would wrongly call their leave unpaid. safety_net.avg_commute_minutes is a ONE-WAY commute, a single leg rather than a daily round trip: report it as "about N minutes each way", and double it yourself if the user asked what they spend commuting per day. It is door to door, averaged over every commuter regardless of mode, for the metro area, and excludes people who work from home. Read-only, no side effects; returns a text summary plus structured JSON.
rank_cities
Rank supported cities by composite quality-of-life score across five weighted dimensions (financial, healthcare, vacation, childcare, safety_net). Returns top N (default 10), with filters for country, countries, region (europe/asia/north_america/south_america/oceania), has_universal_healthcare, include_cities, and exclude_cities. Use this to shortlist across many cities; for a head-to-head between two named cities use compare_cities. The same scenario is applied to every city so scores are directly comparable (default: single person, 2BR rent, $100k USD-equivalent gross). Read-only, no side effects; returns a text summary plus structured JSON.
get_safety_net
Batch lookup of safety-net values for 1 to 20 cities at once: parental leave weeks + how it is paid, universal healthcare flag, vacation days, public holidays (public_holidays is the count the statute lists; public_holidays_effective is how many of those fall on a working day once you account for whether the country replaces a weekend holiday, so quote the effective figure whenever you compare two places on time off), plus each city's safety_net dimension score (0-100) for relative strength. This is the only tool that accepts many cities in one call: use it to line several places up on family / leave / healthcare benefits. On parental leave, quote parental_leave_summary rather than composing your own line from parental_leave_paid_pct: Ireland, Australia, the UK, Czechia and part of Sweden pay a flat weekly cash sum instead of a share of salary, so their headline percentage is 0 or partial and reading it alone would wrongly call their leave unpaid; Germany pays a percentage up to a monthly cap (parental_leave_capped) and pays nothing at all above a household-income ceiling. Check parental_leave_basis (percentage / flat / capped / mixed / unpaid) before making any claim about pay. On sick pay, quote sick_leave_policy rather than composing your own line from sick_leave.phases: it is the STATUTORY FLOOR for someone in their first year of service, phases run one AFTER another rather than stacking, and the durations carry units that differ by country (Slovenia counts working days, Denmark counts calendar days), so sick_leave.paid_weeks is deliberately null wherever the phases are measured against different reference periods and no single total exists. For one city's full profile (tax shape + costs + safety net together) call get_city_summary instead; for a two-city head-to-head that includes cost-of-living use compare_cities. Read-only, no side effects; returns a text summary plus structured JSON.
get_inbound_tax_regime
Look up a city's inbound-worker tax regime, the special reduced-tax schemes for relocating workers that general cost-of-living tools do not surface. Returns regime=null when the country has no modeled regime, which is most cities. Modeled across 13 regimes in Belgium, Denmark, Germany, Greece, Ireland, Italy, Netherlands, Norway, Poland, Portugal, Spain, Sweden and the UK. Roughly half grant an actual reduction (a reduction_pct or a flat_rate) and the rest are note-only: the regime exists but grants a relocating employee nothing, so reduction_pct and flat_rate are null and the take-home is computed on ordinary tax. Each entry returns the mechanic, duration, income cap if any, and a note stating the salary floor where one exists and which eligibility conditions we do not test. Read-only, no side effects; returns a text summary plus structured JSON.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"cityparity: cost-of-living & quality-of-life comparison": {
"cityparity": {
"command": "npx",
"args": [
"-y",
"cityparity-mcp"
]
}
}
}
}McpServers
{
"cityparity": {
"command": "npx",
"args": [
"-y",
"cityparity-mcp"
]
}
}cityparity MCP server
Cost-of-living and quality-of-life comparison tools that AI agents can call. Point an agent at two cities and it returns take-home pay, a full cost breakdown, the equivalent salary you'd need in the target city, and the non-cash deltas people actually move for: vacation, parental leave, universal healthcare.
Hosted at https://mcp.cityparity.com/mcp. Free, no API key, rate-limited at the edge. Built on the Model Context Protocol (spec 2025-06-18, Streamable HTTP).
- Site: <https://cityparity.com>
- Install docs (every client): <https://cityparity.com/mcp>
- Machine-readable docs: <https://mcp.cityparity.com/llms.txt>
- OpenAPI (REST mirror): <https://mcp.cityparity.com/openapi.json>
What it covers
About 165 cities across 69 countries. Most calculators stop at salary and rent. cityparity prices the social safety net (childcare subsidies, parental leave, statutory vacation, universal healthcare), so "the lower-salary city actually pays more" stops being a hand-wave and becomes a number.
Tools
| Tool | What it does |
|------|--------------|
| compare_cities | Full scenario comparison between two cities: take-home, cost breakdown, equivalent target salary, lifestyle deltas, quality score. |
| list_cities | Discover supported city slugs, grouped by country. |
| get_city_summary | One-city profile: tax shape, headline costs, safety-net values. |
| rank_cities | Top N cities by composite quality score, with custom weights and region/country filters. |
| get_safety_net | Parental leave, universal-healthcare flag, vacation, public holidays for 1 to 20 cities. |
| get_inbound_tax_regime | Inbound-worker regimes: Italy impatriati, Portugal IFICI, Belgium expat, Poland B2B ryczałt, Greece inbound. |
City slugs are kebab-case (san-francisco, hong-kong). Call list_cities first if you're unsure.
Connect
Most modern clients speak Streamable HTTP and need no install. Just point them at the URL.
Claude Code
claude mcp add --transport http cityparity https://mcp.cityparity.com/mcp
Claude Desktop / ChatGPT Desktop
{
"mcpServers": {
"cityparity": {
"url": "https://mcp.cityparity.com/mcp"
}
}
}
Claude Desktop config lives at ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows). ChatGPT Desktop uses …/OpenAI/ChatGPT/mcp.json. Restart the app after editing.
Cursor
{
"name": "cityparity",
"url": "https://mcp.cityparity.com/mcp"
}
Codex CLI
mcpServers:
cityparity:
url: https://mcp.cityparity.com/mcp
Stdio-only clients (this package)
If your client can't do HTTP MCP yet, the npm package in this repo bridges stdio → HTTP:
{
"mcpServers": {
"cityparity": {
"command": "npx",
"args": ["-y", "cityparity-mcp"]
}
}
}
The bridge (this package)
cityparity-mcp is a ~150-line stdio→HTTP forwarder. It reads line-delimited JSON-RPC from stdin, POSTs each line to the MCP endpoint, and writes the responses back to stdout (streaming SSE line by line). That's the whole job: no data, no calc engine, no secrets. Read bin/cityparity-mcp.mjs if you want to verify.
npm install -g cityparity-mcp # or use npx, as above
| Env var | Default | Purpose |
|---------|---------|---------|
| CITYPARITY_MCP_URL | https://mcp.cityparity.com/mcp | Override the upstream endpoint (local dev) |
| CITYPARITY_MCP_DEBUG | unset | Log request/response framing to stderr |
Run the tests (zero dependencies, Node ≥ 20):
npm test
Methodology
The full methodology (how taxes, costs, childcare subsidies, and safety-net scoring work) is on the homepage. One thing worth flagging: RSU income is not an input. Grants are treated as source-only because they usually don't follow you across employers. If you're keeping a US employer remotely, treat the result as directional in that direction.
Privacy
Queries reach mcp.cityparity.com and nothing else. No accounts, no client-side telemetry, nothing personally identifiable logged beyond standard HTTP server logs.
License
MIT. cityparity's underlying data and calculation engine are not part of this package. This repo is the public MCP surface plus the open-source stdio bridge.
---
Found a bug or want a city added? <https://cityparity.com/contact/>
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
