Metadata-Version: 2.4
Name: fless-mcp
Version: 1.6.0
Summary: Apartment hunting in California, District of Columbia, Florida, Georgia, Massachusetts, Maryland, North Carolina, Nevada, New York, Pennsylvania, South Carolina, Tennessee, Virginia: live rents, WalkRating scores, neighborhoods. Stdio proxy to https://mcp.fless.io/mcp.
Author-email: Fless <dev@folyfoly.com>
License: MIT
Project-URL: Homepage, https://fless.io/ai-agents
Project-URL: Documentation, https://fless.io/hunt-how-to.md
Project-URL: Repository, https://github.com/fless-io/skills
Project-URL: Changelog, https://github.com/fless-io/skills/blob/main/CHANGELOG.md
Keywords: mcp,apartment,apartments,hunting,rental,ai,agent,llm,florida,georgia,maryland,virginia
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# fless-mcp

[Fless](https://fless.io) apartment-hunting tools for any MCP-capable AI agent: a zero-dependency stdio proxy to the hosted Fless MCP server at `https://mcp.fless.io/mcp`.

## What it does

Your agent researches apartments with live Fless data and hands you a pre-filled hunt link:

- **search_cities**: live + coming-soon cities
- **get_city_overview**: neighborhoods with median rents + WalkRating(TM) scores
- **get_neighborhood**: full detail (rents, scores, POI counts)
- **get_hunt_requirements**: every hunt field, enum, binary restriction (55+, pets, smoking), transparent pricing
- **build_hunt_link**: validate a brief, get a URL that pre-fills the entire hunt form
- **check_hunt_link**: created → opened → started lifecycle
- **search / fetch**: ChatGPT deep-research compatibility pair
- **request_city**: ask Fless to expand to a new city (write tool, rate-limited)
- **get_city_request_stats**: see which cities have the most demand
- **submit_error_report**: report problems with tools or data (write tool, rate-limited)

Research and hand-off tools are anonymous, no key needed. Your human creates the account, verifies email, approves the matched buildings, and pays. Agents never do.

Hunts NEVER contact buildings automatically: all hunts (2.0.0 approval gate) run an instant matched-building list at creation, park at an approval gate, and Fless contacts only the buildings the human explicitly approves in their dashboard, by email when one is on file or via the building's website contact form otherwise (2.1.0). The review also offers Close Matches, near-miss proposals the human adds one by one. Fail-closed: untouched buildings are removed.

Licensed realtors with a Fless for Realtors account ($49.99/mo flat, 15-day free trial) get 8 authenticated `realtor_*` tools (client funnel: invite, hunt, curate, send to client) by sending an API key from fless.io/realtor as `Authorization: Bearer fless_ak_...` on every MCP call. Anonymous callers keep the public toolset.

## Where we operate

<!-- city-coverage:start -->

Fless currently runs apartment hunts in **California / District of Columbia / Florida / Georgia / Massachusetts / Maryland / North Carolina / Nevada / New York / Pennsylvania / South Carolina / Tennessee / Virginia**.
The authoritative live list is [CITIES.md](CITIES.md), auto-generated from
the production API.

| ✅ Live now | 🚧 Coming soon |
|---|---|
| Alexandria, VA | Rockville, MD |
| Annapolis, MD | Silver Spring, MD |
| Arlington, VA | Virginia Beach, VA |
| Ashburn, VA |  |
| Atlanta, GA |  |
| Baltimore, MD |  |
| Bethesda, MD |  |
| Boston, MA |  |
| Brandon, FL |  |
| Burlington, NC |  |
| Charlotte, NC |  |
| Charlottesville, VA |  |
| Chesapeake, VA |  |
| Columbus, GA |  |
| Daytona Beach, FL |  |
| Fort Lauderdale, FL |  |
| Frederick, MD |  |
| Gastonia, NC |  |
| Hampton, VA |  |
| Hillsborough, NC |  |
| Jacksonville, FL |  |
| Kennett Square, PA |  |
| Kernersville, NC |  |
| Key Biscayne, FL |  |
| Kissimmee, FL |  |
| Lake Panasoffkee, FL |  |
| Leesburg, VA |  |
| Manhattan, NY |  |
| Memphis, TN |  |
| Miami, FL |  |
| Miami Beach, FL |  |
| Middle River, MD |  |
| Midlothian, VA |  |
| Naples, FL |  |
| Nashville, TN |  |
| North Port, FL |  |
| Orlando, FL |  |
| Parkville, MD |  |
| Philadelphia, PA |  |
| Pittsburgh, PA |  |
| Prince Frederick, MD |  |
| Raleigh, NC |  |
| Reno, NV |  |
| Richmond, VA |  |
| Rock Hill, SC |  |
| San Diego, CA |  |
| Sanford, FL |  |
| Severn, MD |  |
| Signal Mountain, TN |  |
| Sterling, VA |  |
| Tampa, FL |  |
| Towson, MD |  |
| Vero Beach, FL |  |
| Warsaw, VA |  |
| Washington, DC |  |
| Woodbridge, VA |  |

<!-- city-coverage:end -->

**Your city not listed?** We're expanding. Check back, or join the waitlist at
[fless.io](https://fless.io). Agents: always call `search_cities` first.

## Install

### Claude Desktop / any stdio MCP client

```json
{
  "mcpServers": {
    "fless": {
      "command": "uvx",
      "args": ["fless-mcp"]
    }
  }
}
```

Or with pip:

```bash
pip install fless-mcp
fless-mcp   # speaks JSON-RPC on stdio
```

### Remote (no install needed)

Most clients connect to the hosted server directly:

```
https://mcp.fless.io/mcp
```

See per-assistant setup guides (Claude, ChatGPT, Perplexity, Grok, Mistral Vibe, Codex, OpenClaw, Hermes): **https://fless.io/ai-agents**

## Environment

| Variable | Default | Purpose |
|---|---|---|
| `FLESS_MCP_URL` | `https://mcp.fless.io/mcp` | Remote server (fallback: `https://www.fless.io/mcp`) |
| `FLESS_MCP_UA` | `fless-mcp/<package version> (+https://fless.io/ai-agents)` | User-Agent |

## The skill (recommended companion)

`fless-apartment-hunt`: an [Agent Skills](https://agentskills.io)-standard skill that teaches your agent the full workflow:

```bash
hermes skills install well-known:https://fless.io
# or from GitHub:
npx skills add fless-io/skills
```

## License

MIT
