# Tu Lugar MCP Server

MCP server for [Tu Lugar](https://tulugar.com) — search real estate listings, development projects, companies, and market data in Paraguay and Latin America, straight from Claude, ChatGPT, Cursor, or any MCP client.

**Website → [tulugar.com](https://tulugar.com)**  ·  **Connector docs & one-click setup → [tulugar.com/mcp](https://tulugar.com/mcp)**

## Tools

| Tool | Description |
|------|-------------|
| `search_listings` | Search listings by city, price, bedrooms, property type, etc. |
| `get_listing` | Get full listing detail by ID or slug |
| `search_projects` | Search development projects (verified first, available units) |
| `get_project` | Get project detail with units, prices, and developer info |
| `search_companies` | Search real estate agencies and developers |
| `list_locations` | List countries, cities, or neighborhoods with listing counts |
| `get_market_summary` | Market stats: avg price, median, price/m², counts |
| `get_str_data` | Airbnb/STR city-level data: nightly rates, occupancy stats |
| `mortgage_calculator` | Estimate monthly payment, total interest, and debt-to-income |

> **This npm package is read-only.** To **create / edit / publish listings** or
> **contact agents** (the agent + buyer write tools), connect the remote OAuth
> connector instead — see [Remote connector (write access)](#claude-desktop-remote--write-access)
> below. Writes require an authenticated Tu Lugar account and aren't available
> over the local stdio transport.

## Install

### Claude Desktop (local)

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "tulugar": {
      "command": "npx",
      "args": ["-y", "@tulugar/mcp-server"]
    }
  }
}
```

### Claude Desktop (remote — write access)

Settings → Connectors → Add custom connector → URL: `https://tulugar.com/api/mcp`

The remote connector serves the same read tools **plus** the OAuth-gated write
tools. Ask Claude to connect (or use the `connect_account` tool) and it runs the
OAuth consent flow once so the connector can act on your behalf:

- **Connect:** `account_status` (is my account connected / can I publish?),
  `connect_account` (returns a one-tap link to connect your Tu Lugar account)
- **Agents:** `create_listing`, `upload_listing_image`, `edit_listing`,
  `publish_listing`, `my_listings`, `my_inquiries`,
  `share_listing_whatsapp` (ready-to-send WhatsApp message + branded image for a listing)
- **Buyers:** `create_lead` (contact an agent — works without an account)

### Claude Code

```bash
claude mcp add tulugar -- npx -y @tulugar/mcp-server
```

### Cursor / Windsurf

Same JSON config format as Claude Desktop.

## Example Queries

Once connected, try asking:

- "Find me a 2-bedroom apartment in Asuncion under $100,000"
- "What are the average apartment prices in Villa Morra?"
- "Show me development projects under construction"
- "What's the Airbnb occupancy rate in Asuncion?"
- "List verified real estate developers in Paraguay"

## Configuration

| Env Variable | Default | Description |
|-------------|---------|-------------|
| `TULUGAR_API_URL` | `https://tulugar.com/api/v1` | API base URL |
| `TULUGAR_SITE_URL` | `https://tulugar.com` | Site URL for listing links |

## Links

- [Connector home](https://tulugar.com/mcp)
- [API Documentation](https://tulugar.com/developers)
- [OpenAPI Spec](https://tulugar.com/api/v1/openapi.json)
- [Tu Lugar](https://tulugar.com)

## License

MIT