Metadata-Version: 2.4
Name: fless-mcp
Version: 1.4.1
Summary: Fless apartment-hunting MCP server (stdio proxy to https://mcp.fless.io/mcp): research cities, neighborhoods, rents, and build pre-filled hunt links.
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,hunting,rental,ai,agent,llm
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 email buildings automatically: all hunts (2.0.0 approval gate) run an instant matched-building list at creation, park at an approval gate, and Fless emails only the buildings the human explicitly approves in their dashboard. 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

Fless currently runs apartment hunts in **Florida / Maryland / Virginia**.
The authoritative live list is [CITIES.md](CITIES.md), auto-generated from
the production API.

| ✅ Live now | 🚧 Coming soon |
|---|---|
| Miami, FL | Washington, DC |
| Naples, FL | Rockville, MD |
| Annapolis, MD | Silver Spring, MD |
| Baltimore, MD | Virginia Beach, VA |
| Frederick, MD | |
| Alexandria, VA | |
| Arlington, VA | |
| Charlottesville, VA | |
| Chesapeake, VA | |
| Hampton, VA | |
| Richmond, VA | |
| Leesburg, VA | |

**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/1.3.0 (+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
