sg-housing-data

Singapore housing/property data tools for AI agents.

This package provides a local MCP server for Claude Desktop, Claude Code, Codex CLI, and other MCP clients. It exposes curated HDB, CEA, data.gov.sg, and URA private residential data through bounded, agent-friendly tools, plus link-out discovery for current PropertyGuru Singapore listings.

data.gov.sg queries work out of the box through a maintained proxy. Detailed URA private-residential tools require an explicitly configured SG_HOUSING_URA_TOKEN_BROKER_URL, or URA_ACCESS_KEY in an approved development environment; the package does not embed credentials or an unauthenticated public URA proxy.

Install

Install the latest package:

npm install -g sg-housing-data@latest

Requires Node.js 20 or newer.

Optional health check:

sg-housing doctor --mcp --json

Expected result:

• distribution_mode is public without an explicit URA broker, maintained with one, or development with a local key
• data_gov_credentials is ok
• ura_credentials is ok when an explicit broker or development key is configured; otherwise unavailable is expected
• mcp_stdio is ok
• propertyguru_listings is ok in the default link_out mode

Claude Desktop

Claude Desktop uses claude_desktop_config.json.

Open Claude Desktop, then go to:

Settings -> Developer -> Edit Config

Add this server:

{
  "mcpServers": {
    "sg-housing": {
      "command": "npx",
      "args": ["-y", "sg-housing-data@latest", "mcp"]
    }
  }
}

Config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\\Claude\\claude_desktop_config.json

After saving the file, fully quit and restart Claude Desktop. The MCP indicator should show sg-housing.

Try:

Use sg-housing to check recent 5-room HDB resale transactions in Bukit Merah.

Use sg-housing to find recent D'LEEDON private sale comparables and summarize price PSF.

For multi-project private-sale trends, ask for analysis rather than row-by-row comparables:

Use sg-housing to compare Parc Riviera, Normanton Park, Parc Esta, D'Leedon, and Sims Urban Oasis from 2025-Q1 to 2026-Q2 by quarter, with all transactions and a large-unit area proxy segment.

Claude Code

Add the MCP server at user scope:

claude mcp add --transport stdio --scope user sg-housing -- npx -y sg-housing-data@latest mcp

Verify:

claude mcp list

Inside Claude Code, run:

/mcp

Project-scoped alternative:

claude mcp add --transport stdio --scope project sg-housing -- npx -y sg-housing-data@latest mcp

Codex CLI

Add the MCP server:

codex mcp add sg-housing -- npx -y sg-housing-data@latest mcp
codex mcp list

Or edit ~/.codex/config.toml:

[mcp_servers.sg-housing]
command = "npx"
args = ["-y", "sg-housing-data@latest", "mcp"]
enabled = true
startup_timeout_sec = 30
tool_timeout_sec = 120

Restart Codex after changing the config.

Example Use Cases

Once configured, ask housing questions directly in your agent. The MCP server keeps tool calls bounded, returns compact data, and lets the agent write the final summary.

Tool choice:

• Use search_property_listings for current advertised sale/rental inventory. Public v1 returns a filtered PropertyGuru URL and an explicit filter report; it does not extract or republish listing cards.
• Use analyze_private_residential_sales for multi-project private condo trend tables, quarterly/monthly/yearly grouping, all-vs-segment comparisons, and metrics such as count, price_median, price_psf_median, and area_sqm_median.
• Use find_private_residential_sale_comparables for compact evidence rows or capped shortlist summaries after narrowing by project, district, budget, area, sale type, or date.
• URA private sale transactions do not include bedroom count. For "3 bedder and above" sale analysis, pass an explicit area-based proxy segment and report that assumption.

Example active-listing request:

Find The Minton's newest three-bedroom listings.

The agent can call search_property_listings with:

{
  "search_text": "The Minton",
  "bedrooms": [3],
  "sort": "newest"
}

Every listing-tool field is optional. {} is valid and produces a bounded default sale-search link. Singapore districts accept D01–D28 and aliases such as 9, 09, or d9. In public v1, search_text is deliberately broad; exact project, areas, hdb_estates, mrt_stations, address, and postal_code inputs fail with an actionable error until an exact resolver ships. The response distinguishes applied, partial, default, and unapplied constraints so an agent cannot silently overstate a provider filter.

The same service is available from the CLI:

sg-housing listings --search-text "The Minton" --bedrooms 3 --sort newest --json
sg-housing listings --districts D09,D10 --property-category condo --max-price 3000000 --json

The default SG_HOUSING_PROPERTYGURU_MODE=link_out needs no PropertyGuru login and performs no page extraction. disabled removes the MCP tool. rows is reserved and fails closed with PROVIDER_POLICY_BLOCKED: the observed propertyguru search command comes from a maintainer-local plugin, not the official OpenCLI package, and automated collection/republication requires a separately approved provider-policy basis. OpenCLI is therefore not an install or runtime dependency of this public release.

Troubleshooting: run sg-housing doctor --mcp --skip-update-check --json. If listing discovery was disabled unintentionally, remove the environment variable or set SG_HOUSING_PROPERTYGURU_MODE=link_out, then restart the MCP client. If rows was set, switch to link_out; installing OpenCLI alone does not enable extraction in this package version.

Example analyze_private_residential_sales request shape for a five-project quarterly workflow:

{
  "projects": ["PARC RIVIERA", "NORMANTON PARK", "PARC ESTA", "D'LEEDON", "SIMS URBAN OASIS"],
  "from": "2025-01",
  "to": "2026-06",
  "group_by": ["project", "quarter"],
  "segments": [
    { "name": "all" },
    {
      "name": "large",
      "filters": { "area_sqm": { "gte": 90 } },
      "proxy_for": "3 bedrooms or larger",
      "unavailable_field": "bedrooms",
      "proxy_field": "area_sqm"
    }
  ],
  "metrics": ["count", "price_median", "price_psf_median", "area_sqm_median"],
  "output": "long_table"
}

The response puts the analysis table under data.rows with data.columns, structured proxy notes under data.assumptions, and scan diagnostics such as resolved URA batches under data.diagnostics.

Optional experimental skill:

npx skills add StevenSLXie/sg_prop_cli --skill sg-property-client-report

The skill adds a client-report workflow for Singapore private residential decisions. It supports both broad buyer briefs and specific project deep dives, then combines sg-housing transaction evidence with external project metadata, layout checks, active listings, liquidity, peer comparison, and an objective recommendation.

Notes:

• HDB and CEA data come from public data.gov.sg sources.
• data.gov.sg uses a maintained proxy by default; URA private-residential tools require an explicitly configured broker or development key.
• CEA transaction records do not include transaction prices.
• URA private sale records do not include unit numbers; coordinates are project-level.
• Results are not valuation advice.

Maintainers

Release checks:

npm run prepublishOnly
npm pack --dry-run

Maintained proxy details are in docs/VERCEL_PROXY.md. npm release steps are in docs/NPM_RELEASE.md.