streeteasy-mcp

A remote MCP server that wraps the StreetEasy GraphQL API so an LLM agent can search and parse NYC rental listings.

It vendors the streeteasy-api client (v0.4.0) and exposes it over either stdio (local) or Streamable HTTP (remote) transport, so it can be connected to by Claude or any MCP client.

Tools

search_rentals accepts area names ("MANHATTAN", "Williamsburg", "upper east side") or numeric codes, and validates amenity tokens against the known set.

Media

Photos resolve to Zillow's CDN (photos.zillowstatic.com/fp/{key}-se_large_800_400.jpg), videos to their provider watch URL (YouTube/Vimeo) plus a thumbnail, and 3D tours to a direct tour3dUrl. All are public — no auth required.

Not included: contact info & inquiries

Listing agent contact details and "request a tour" inquiries are not exposed. They live behind StreetEasy's contact flow, which is protected by PerimeterX bot-detection (a "Press & Hold" human check). Automating it would mean evading bot-detection, so it's intentionally left out — the right pattern is to surface the listing url and let a human submit the tour request in their browser.

Related MCP server: Apartment Hunter MCP Server

Endpoints

• POST /mcp — the MCP Streamable HTTP endpoint (stateless). Requires a bearer token unless MCP_DISABLE_AUTH is set — see Authentication.

• GET / and GET /health — health checks.

• OAuth: /.well-known/oauth-authorization-server, /.well-known/oauth-protected-resource, /register, /authorize, /token, /revoke.

Run as a local MCP server (recommended)

Runs over stdio from your machine's residential IP — the configuration that actually reaches StreetEasy.

npm install
npm run build
# register with Claude Code (uses the stdio entry point):
claude mcp add streeteasy -- node "$(pwd)/dist/stdio.js"

Then ask Claude to search rentals. To run the stdio server by hand:

npm run start:stdio

Run as an HTTP server

npm install
npm run build
npm start            # listens on $PORT (default 3000), POST /mcp

Test it with the MCP SDK client (see test-client.mjs):

MCP_URL=http://localhost:3000/mcp node test-client.mjs

Configuration

Authentication (OAuth 2.1 + Dynamic Client Registration)

The HTTP transport requires OAuth by default — MCP clients (Claude, etc.) run the standard authorization flow automatically, so you usually don't configure anything. The server is a self-contained OAuth 2.1 authorization server:

• Advertises metadata at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource.

• Supports Dynamic Client Registration (RFC 7591) at /register, so clients self-register with no manual client_id / client_secret.

• /authorize (PKCE S256 required) → /token (authorization-code + refresh), with /revoke for revocation.

• Unauthenticated POST /mcp returns 401 with a WWW-Authenticate header pointing at the protected-resource metadata, which kicks off discovery + DCR.

Because the tools expose only public listing data, there's no per-user login: authorization is auto-approved and the issued bearer token simply gates /mcp. Tokens are held in memory (single replica); a restart just makes clients transparently re-register. Set MCP_DISABLE_AUTH=1 to turn the whole layer off.

Proxy / bot-detection

StreetEasy 403s datacenter IPs, so any cloud host (Railway included) must send upstream requests through a residential proxy. Set STREETEASY_PROXY to a proxy URL (credentials may be embedded, e.g. http://user:pass@host:port) and all StreetEasy GraphQL traffic is tunnelled through it. On startup the server logs the proxy in use with credentials redacted (Outbound proxy: http://***:***@host:port).

Rotating residential proxies hand out a fresh exit IP per connection, and a clean IP isn't guaranteed every time, so the client automatically retries a 403 bot-challenge (up to 3 times when a proxy is set) to land on a good IP. A local stdio server on a residential connection doesn't need a proxy.

Deploy on Railway

This repo ships a Dockerfile. With the Railway CLI:

railway login
railway init --name streeteasy-mcp
# Cloud hosts are datacenter IPs — set a residential proxy so calls aren't 403'd:
railway variables --set "STREETEASY_PROXY=http://user:pass@host:port"
railway up
railway domain          # generate a public URL
# Set the OAuth issuer to your public URL (or rely on RAILWAY_PUBLIC_DOMAIN):
railway variables --set "PUBLIC_BASE_URL=https://<your-app>.up.railway.app"

Connect from Claude Code

claude mcp add --transport http streeteasy https://<your-app>.up.railway.app/mcp

The client discovers the OAuth endpoints and registers itself automatically (Dynamic Client Registration) — no client_id / token to configure.