Housing Sentinel

What housing-sentinel MCP server does

housing-sentinel connects AI agents and automation workflows to Housing Sentinel, a housing-market data service covering Shenzhen, Shanghai, Beijing, Guangzhou, Hangzhou, Nanjing, Suzhou, Wuxi, Chengdu, Chongqing, Dongguan, and Xiamen. The service collects officially published residential transaction and inventory data, then calculates inventory digestion periods and assigns one of four market stages: defense, observation, attack, or rapid attack.

Available data includes first-hand and second-hand residential transactions, inventory, monthly-average transaction volume, inventory digestion cycles, threshold metadata, and current market signals. Update frequency follows the source city’s publication schedule; most data is updated daily, while some cities or indicators use weekly or monthly official figures.

The market-stage framework primarily uses the second-hand inventory cycle. Cities without that metric use transaction-volume thresholds instead. The service states that second-hand signals take precedence when first-hand and second-hand signals differ. These outputs are market-timing references, not investment advice.

How it works

The recommended connection uses the remote MCP endpoint at https://api.housingsentinel.cn/mcp. MCP clients authenticate with an API key sent as a Bearer token. The exposed tools are list_cities, get_market_signal, get_metrics, and get_history.

list_cities returns available or subscribed cities and their threshold metadata. get_market_signal retrieves the current stage for a city. get_metrics provides a daily indicator time series, with a default range of about 90 days. get_history returns raw daily transaction and inventory data, with a maximum of 400 records per request.

The MCP service also provides the daily_brief and compare_cities prompts, plus resources for connection notes and city thresholds. For clients that only support local stdio connections, the repository includes an npm bridge that forwards stdio messages to the remote service.

Setup and configuration

Create an account on the Housing Sentinel website or its mini program, then generate an API key from the AI-agent access page. Configure the remote MCP server with the URL and an Authorization: Bearer hs_live_... header. Claude Code can add the server with its HTTP transport command; Claude Desktop and Cursor can use an MCP configuration containing the same URL and header.

The stdio bridge can be started with npx -y housing-sentinel-mcp. Set HOUSING_SENTINEL_API_KEY in its environment. Users in mainland China may optionally set HOUSING_SENTINEL_URL to the documented proxy endpoint.

The repository also supplies an OpenAPI 3.0 file for REST clients and workflow tools such as n8n, Dify, and Coze. A public city-card endpoint can be queried without a key, but it only returns a limited current snapshot.

Tools and capabilities

• Query the current signal for one city or subscribed cities.
• Compare cities using current market-stage data.
• Retrieve transaction, inventory, and digestion-cycle metrics over time.
• Fetch raw historical records for supported date ranges.
• Poll only changed signal data with since and weak ETags through the REST API.
• Register webhooks for data updates or market-stage changes on eligible plans.
• Use Node.js or Python examples for webhook signature verification.
• Install a Claude Skill containing the documented interpretation framework.

Limitations and notes

The housing-sentinel MCP server requires an account key for most MCP operations, and access depends on the account’s trial, free, points, subscription, or institution plan. After the three-day trial, the free tier is limited to Shenzhen’s current signal and has lower request limits; historical metrics and history are unavailable there. Historical access, city coverage, request quotas, and webhook access vary by plan.

Data is limited to the supported Chinese cities and follows each source authority’s reporting cadence. The service recommends polling no more frequently than hourly because the underlying data generally updates once per day. API data is intended for the account holder and must not be republished as an external data service. Webhook destinations must use HTTPS, respond within five seconds, and can be disabled after repeated failures. The repository contains integration documentation and examples, not the Housing Sentinel service implementation.