evlek-mcp

# Evlek MCP Server

[![MCP](https://img.shields.io/badge/MCP-2026--07--28-7B61FF?style=flat-square)](https://modelcontextprotocol.io)
[![Hosted](https://img.shields.io/badge/Hosted-evlek.app-0A2540?style=flat-square)](https://evlek.app/api/mcp)
[![License](https://img.shields.io/badge/License-MIT-2D8B5C?style=flat-square)](LICENSE)
[![Coverage](https://img.shields.io/badge/Coverage-North_Cyprus-C9A157?style=flat-square)](https://evlek.app)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-app.evlek-B84E3B?style=flat-square)](https://registry.modelcontextprotocol.io)
[![smithery badge](https://smithery.ai/badge/onurd8898/evlek)](https://smithery.ai/servers/onurd8898/evlek)

> AI-native property discovery for North Cyprus (KKTC). Built on the Model Context Protocol — works in Claude, ChatGPT, Gemini, Cursor, and any MCP-compatible client.

The Evlek MCP server gives AI agents structured, real-time access to North Cyprus property data — search active listings, compare cities and districts, and track the price index. All data is sourced live from [evlek.app](https://evlek.app). Evlek does not offer a rental-yield or investment-return estimate: figures are descriptive asking-price facts only, never a valuation, forecast, or recommendation. Title-deed (koçan) and legal-procedure tools are deliberately **not** part of the surface: that taxonomy has not passed an independent KKTC legal audit.

## License scope

This repository is MIT-licensed for the public manifest, documentation, examples, and reference clients contained here. The hosted Evlek service, evlek.app web app, mobile apps, listing database, AI prompts, business logic, brand assets, name, logo, and trade dress remain proprietary and are not licensed under MIT. See [LICENSE](./LICENSE) for details.

---

## Why Evlek MCP

- **AI-first.** Built for agentic workflows from day one — not retrofitted on a legacy listing API.
- **Multilingual.** Answers in TR, EN, RU, DE, AR: pass `locale` (or write the `search` query in that language) and the text, amenity names, number formats and links follow it. Place names are resolved in any of the five languages.
- **Verification-aware listings.** Evlek surfaces listing and account verification context where available, and the MCP omits contact fields to preserve Evlek's reveal/contact funnel.
- **Built for the region.** Optimized for the 6 cities of North Cyprus (Lefkoşa, Girne, Gazimağusa, İskele, Güzelyurt, Lefke) and 100+ districts.
- **Production-grade.** OWASP MCP Top 10 aligned — Zod input validation, output sanitization, rate limiting (60/min/IP, 500/min global), Sentry observability.

---

## Quick start

### Remote-capable clients (preferred)

Most modern MCP clients (Claude, Cursor, VS Code) connect directly to the Streamable HTTP endpoint — no local bridge needed:

```json
{
  "mcpServers": {
    "evlek": {
      "url": "https://evlek.app/api/mcp"
    }
  }
}
```

### ChatGPT (connector + Deep Research)

Add `https://evlek.app/api/mcp` as a custom connector. Evlek exposes OpenAI-compatible `search` and `fetch` tools, so it works in ChatGPT connectors and Deep Research in addition to developer mode.

### Claude Desktop (legacy stdio bridge)

If your client only supports stdio servers, use the pinned `mcp-remote` bridge. Add this to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "evlek": {
      "command": "npx",
      "args": ["-y", "mcp-remote@0.1.16", "https://evlek.app/api/mcp"]
    }
  }
}
```

Restart Claude Desktop. The "evlek" server appears in the tools list.

### MCP Inspector (test before installing)

```bash
npx @modelcontextprotocol/inspector https://evlek.app/api/mcp
```

### Direct API (cURL)

```bash
curl -X POST https://evlek.app/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

More configs: [`examples/`](./examples/)

---

### Local stdio server (this repository)

This repo is also a runnable MCP server. It answers `initialize` / `tools/list` entirely locally from the embedded tool contract ([`tools.json`](./tools.json)) and fetches live data from the Evlek data API when a tool is called. It only implements tools — it does not declare the `resources` or `prompts` capability, so `resources/list` and `prompts/list` return a normal MCP "method not found" error on this bridge; those primitives (see below) are hosted-endpoint-only, reachable via the Streamable HTTP URL above. It also speaks whatever MCP protocol version the pinned `@modelcontextprotocol/sdk` supports during `initialize` (currently `2025-11-25`), not necessarily the hosted endpoint's `2026-07-28` — tool schemas are identical either way.

```bash
npx github:Evlek/evlek-mcp        # or: npm install && npm start
```

```json
{
  "mcpServers": {
    "evlek": {
      "command": "npx",
      "args": ["-y", "github:Evlek/evlek-mcp"]
    }
  }
}
```

Smoke-test it (spawns the server and speaks real MCP over stdio):

```bash
npm test              # live: initialize + tools/list + a real tools/call
OFFLINE=1 npm test    # offline: introspection works with zero network
```

## Available tools

<!-- AUTO-GENERATED by `pnpm mcp:export-public` in the source repo (writes `public-mcp-export/README-tools-table.md`) — do not hand-edit this block. -->

**8 tools** · protocol `2026-07-28` · Streamable HTTP JSON-RPC 2.0

| Tool | Title | Description |
|------|-------|-------------|
| `search_listings` | Search Northern Cyprus property listings | Use this when the user wants to find or see property listings; results are shown with real photos in the Evlek widget. Search live Evlek property listings for sale and long-term rent in Northern Cyprus (KKTC/TRNC; prices in GBP unless a currency is given; 2+1 means bedrooms 2) with structured filters: transaction, city, district, property type, bedrooms, price, areas, amenities, nearby university. Pass the user's language as `locale` (tr\|en\|ru\|de\|ar): the text, amenity names, number formats and links follow it. Returns at most 10 listings per call, each as one readable line (type, place, price, rooms, area, a deterministic sentence, data notes, canonical link) plus a structured card; continue with the `nextCursor` of a group. Without `transaction`, listings for sale and for rent come as two separate groups, each with its own cursor that is only valid together with that group's transaction. Place names in any language are resolved; an unknown place returns suggestions instead of results. An amenity that cannot be filtered on is reported as not applied. For one listing use `get_listing`. Returns advertised asking-price and listing facts only: not a valuation, verification of property-specific claims, forecast, ranking or recommendation. |
| `search` | Search Evlek property listings | Use only for research and citation lookups (deep research). To show listings to the user, use search_listings instead. Search live Northern Cyprus (KKTC/TRNC) property listings on Evlek with a free-text query in Turkish, English, Russian, German or Arabic. Returns matching listings as id/title/url for the fetch tool, newest first (sale and rent as two groups when the query names neither). The answer language follows the language of the query. Same data as search_listings: this fixed form exists for the ChatGPT/OpenAI connector contract. Use when: the caller only has a free-text query ("2+1 apartment in Kyrenia under 150000 pounds", "EVL-100464"). Don't use for: structured filters, paging or another answer language: use search_listings. |
| `fetch` | Fetch full Evlek listing detail | Fetch the full detail of one Evlek listing: title, price, location, rooms, areas, amenities, data-quality notes and the canonical link. The id is the listing id (UUID) from a search result, a listing number such as EVL-100464, or an evlek.app listing link; the answer language follows the link (English otherwise). A listing that is not available (it does not exist, is not public, or was removed) always gets the same answer. Same data as get_listing: this fixed id-only form exists for the ChatGPT/OpenAI connector contract. Use when: an id from search is known. Don't use for: discovery (use search first) or another answer language (use get_listing). |
| `get_listing` | Get an Evlek listing | Get the full details of ONE public Evlek listing (sale or long-term rent) in the user's language. `ref` is the listing id (UUID), the listing number (EVL-100464 or just 100464) or an evlek.app listing link in any language. Returns the price, rooms, bathrooms, built area and plot area (always separate), the approximate location, features, the office name, dates, data-quality notes, photos with captions where they exist, AI virtual-staging before/after images when the office approved them (always labelled as AI-generated) and the canonical link. Contact details are never included: send the user to the link. A listing that is unknown or no longer public answers found:false with code NOT_FOUND (this is not an error). Pass the user's language as `locale` (tr, en, ru, de or ar). |
| `compare_listings` | Compare Evlek listings | Compare 2 to 4 public Evlek listings side by side in the user's language: price, price per m² (only when the built area is believable), rooms, bathrooms, built area and plot area (always separate), location, furnishing, key features and data-quality notes, plus a few descriptive highlights (lowest price, largest indoor area, most recently listed). `ids` takes listing ids (UUID), listing numbers (EVL-100464) or evlek.app listing links, in any mix; the order you give is kept. Sale and rent listings are never ranked against each other: a mixed request is shown in two groups with a warning. A reference that is unknown or no longer public is listed in `missingIds` with code NOT_FOUND (this is not an error). Descriptive facts only: no valuation and no recommendation. Pass