com.cityparity/cityparity

Official6 tools

by summerstateofmind · JavaScript

cityparity — Cost-of-Living & Quality-of-Life Comparison

Cost-of-living & quality-of-life comparison: take-home pay, equivalent salary, safety-net deltas.

Cost-of-living and quality-of-life comparison tool for salary and relocation decisions.

Captured live from the server via tools/list.

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.

Parameters (7)

source_citystringrequired
City slug for the user's current city. Use list_cities to discover valid slugs (e.g. 'nyc', 'seattle', 'tokyo').
target_citystringrequired
City slug for the destination city.
gross_salarynumberrequired
User's annual gross salary in the SOURCE city's local currency (e.g. USD for Seattle, NOK for Oslo).
householdobject
Family structure: working-age partner and dependent children. Omit for a single person with no kids.
livingobject
Housing and spending assumptions. Omit to use defaults: rent, 2 bedrooms, typical spending.
advancedobject
Optional fine-tuning: retirement contribution, age bracket, trips home, transit mode, and inbound tax regime. Omit to use defaults.
score_weightsobject
Override the composite-score weights. Defaults: financial 30, healthcare 20, vacation 15, childcare 15, safety_net 20.

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.

Parameters (1)

countrystring
Optional case-insensitive country filter. Use the canonical name as stored in city_data.country (e.g. "Norway", "USA", "United Kingdom"). If omitted, returns all countries.

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. Read-only, no side effects; returns a text summary plus structured JSON.

Parameters (1)

citystringrequired
City slug. Use list_cities to discover valid slugs.

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.

Parameters (4)

weightsobject
Override the composite-score weights. Defaults: financial 30, healthcare 20, vacation 15, childcare 15, safety_net 20.
filterobject
Restrict which cities are ranked, by country, region, universal-healthcare flag, or explicit include/exclude slug lists. Omit to rank all supported cities.
scenarioobject
Override the default ranking scenario. The same scenario is applied to every city so scores are comparable.
limitinteger
Max results to return. Default 10.

get_safety_net

Batch lookup of safety-net values — parental leave weeks + paid percentage, universal healthcare flag, vacation days, public holidays — for 1 to 20 cities at once, 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. 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.

Parameters (1)

citiesarrayrequired
Array of city slugs (1-20). Use list_cities to discover valid slugs.

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 null when the country has no modeled regime (most cities). Modeled regimes: Italy impatriati (Milan, Rome), Portugal IFICI (Lisbon, Porto), Belgium expat (Brussels), Poland B2B ryczałt (Warsaw, Kraków), Greece inbound (Athens). Each entry includes the mechanic (reduction percentage or flat rate), duration, income cap if any, and a conservative eligibility hint. Read-only, no side effects; returns a text summary plus structured JSON.

Parameters (1)

citystringrequired
City slug. Use list_cities to discover valid slugs. Most cities return regime=null because their country has no special inbound-worker tax regime.

README.md4 KBView on GitHub

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

bash

claude mcp add --transport http cityparity https://mcp.cityparity.com/mcp

Claude Desktop / ChatGPT Desktop

json

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

json

{
  "name": "cityparity",
  "url": "https://mcp.cityparity.com/mcp"
}

Codex CLI

yaml

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:

json

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

bash

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

bash

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/

Install

claude_desktop_config.json

{
  "mcpServers": {
    "cityparity": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.cityparity.com/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.