Jabama README

🏡 jabama-mcp: Jabama MCP server for AI agents

Unofficial, read-only MCP server for Jabama (جاباما): let your AI agent plan stays in Iran.
Search villas, suites and eco-lodges with the exact price for your dates and guests, read rules and reviews,
and find group tours, events and theater seats, all from Claude, Cursor or Copilot.

Quick start · What it can do · Tools · FAQ · فارسی

For AI agents

• What: unofficial, read-only MCP server for Jabama (جاباما), the Iranian short-term rental site, plus its tour and event sites. Place names must be in Persian (the agent translates English ones); prices are in Toman.
• Install: claude mcp add jabama -- uvx jabama-mcp (stdio transport; needs Python 3.10+ and uv).
• Auth: none, no API key. Optional JABAMA_MCP_PROXY (HTTP proxy) if Jabama blocks your network.
• Access: read-only. No login, booking, seat holds or payment, so no confirmation is needed before calling tools.
• Tools: 21, all prefixed jb_*. Start with jb_find_destination (or jb_parse_request for free text), then jb_search_stays → jb_stay_calendar → jb_price_quote. Tours: jb_tour_places → jb_search_tours → jb_tour. Events: jb_search_events → jb_event → jb_event_seats.
• Use when: comparing stays, tours, events or theater seats in Iran, or computing the exact total for dates and guests.
• Do not use when: you need to book, pay or hold a seat (the user does that on the site).
• Output: compact JSON. Prices in Toman, dates Gregorian YYYY-MM-DD, ratings 0-5. Pass the numeric listing code (tours: 8-digit id) between tools.
• Machine-readable: server.json; catalog of all Iranian MCP servers: awesome-iran-mcp (TOOLS.md, servers.json, llms.txt).

Why use Jabama MCP

On Jabama (jabama.com) a search card shows one price, but the real cost of a stay depends on the nights you pick (weekends and holidays are priced differently), how many guests come (every guest above the base count adds a nightly charge) and long-stay discounts. An agent with jabama-mcp reads the search, the nightly calendar and the site's own price quote, so the number it gives you is the number you pay:

You: A cheap eco-lodge near Ramsar for 4 people, 20 to 23 October?

Agent: calls jb_find_destination(query="رامسر") → jb_search_stays(keyword="city-ramsar", check_in="2026-10-20", check_out="2026-10-23", guests=4, types=["ecotourism"], sort="cheapest") → jb_price_quote(code=328353, check_in="2026-10-20", check_out="2026-10-23", guests=4)

Night	Type	Night price	2 extra guests	Total
20 Oct	weekday	600,000	300,000	900,000
21 Oct	weekend	520,000	300,000	820,000
22 Oct	weekend	520,000	300,000	820,000

نسا - افرا in Tonekabon: 2,540,000 Toman for 3 nights and 4 guests (or 4 parts of 635,000). The host must accept the booking first; cancelling up to 24 Mehr costs 10% of the first night and 10% of the rest.

_{Real tool output from 2026-10-04; prices change all the time. Prices are in Toman.}

What it can do

• 📍 Find a place: Persian city, area or landmark names (a beach, a mall, an airport) to search filters
• 🗣️ Understand a request: free text like «ویلای استخردار در رامسر برای ۶ نفر» becomes filters, with Jabama's own AI parser
• 🔎 Search stays by dates and guests with type, amenities, region, rooms, price, instant booking and rating filters
• 🧾 Get the exact price for dates and guests, night by night, with discounts and the cancellation windows
• 📅 See the calendar: free nights and nightly prices for the next ~76 days, with weekends and holidays
• ⭐ Check quality: house rules, amenities (and what is missing), reviews, host reputation, similar stays
• 🚌 Group tours (jabama.tours): search, departures with free seats and per-package prices, day plans
• 🎭 Events and theater (jabama.events): what is on, sessions, seats left, free seats by row and price
• 🔒 Read-only by design: no login, no booking, no seat holds, no payment

Quick start

You need uv.

claude mcp add jabama -- uvx jabama-mcp

{
  "mcpServers": {
    "jabama": { "command": "uvx", "args": ["jabama-mcp"] }
  }
}

{
  "servers": {
    "jabama": { "type": "stdio", "command": "uvx", "args": ["jabama-mcp"] }
  }
}

Then just ask:

• "Cheapest villa with a pool in Ramsar for 6 people next weekend, and the exact total?"
• "Which nights is this cottage free in November, and which are cheapest?"
• "A one-day nature tour from Tehran this month, with free seats for 3."
• "What's on in Tehran on Friday evening under 500,000 Toman? Show the free seats."
• قوانین کنسلی جاباما چیست و چقدر از پول برمی‌گردد؟

How it works

  AI agent  (Claude, Cursor, Copilot, ...)
      │
      │  MCP over stdio
      ▼
  jabama-mcp  (runs on your machine)
      │
      │  HTTPS (JSON)
      ├──────▶  gw.jabama.com, www.jabama.com   (stays, help, magazine)
      ├──────▶  api.jabama.tours                 (group tours)
      └──────▶  api.jabama.events, jabama.events (events, theater)

jabama-mcp runs locally and calls the same public endpoints the Jabama websites use. There's no hosted server in between, no API key, and nothing about you is sent anywhere else.

Tools

Listings are identified by their numeric code (328353, the number in jabama.com/stay/ecotourism-328353); tours by an 8-digit id, events and plays by the id in their page URL.

All 21 tools are annotated readOnlyHint: true and return compact structured JSON, so they don't flood the agent's context.

Good to know

• Prices are in Toman everywhere (1 Toman = 10 Rial). The stays API answers in Rial; the server divides by 10. Tours are Toman per person, events and theater Toman per ticket (or per unit, e.g. one boat, when pricing is per_unit).
• Stay prices are for the whole stay for the searched dates and guests (total_price); cheapest_night is the cheapest single night, not the average. Without dates a search prices one default night.
• Stay cards (jb_search_stays, jb_similar_stays) carry image, the cover photo, and url; with dates the url opens the listing on those dates and guests, priced like the quote.
• Count children as guests. The quote has no child price, so guests is everyone who stays.
• Dates are Gregorian YYYY-MM-DD (1405-07-28 = 2026-10-20); times are Tehran local. Stays can be quoted for about the next 76 days.
• jb_price_quote is the number to trust. It is the same read-only quote the listing page shows; it creates no booking. Quotes show no tax line; Jabama's help center says 1.5% tax is added when booking.
• Instant vs request: instant_booking: false means the host must accept first. instant_only keeps only instant listings.
• Tour seats: only jb_tour has correct free seats; tour lists count seats once per package.
• Ratings are 0–5; null means not rated yet. Stay reviews carry only a Jalali month, not a date.

FAQ

npx @modelcontextprotocol/inspector uvx jabama-mcp

Configuration

فارسی: سرور MCP جاباما

claude mcp add jabama -- uvx jabama-mcp

Development

git clone https://github.com/sepehr071/jabama-mcp && cd jabama-mcp
uv sync
uv run pytest            # offline, against recorded responses
uv run pytest -m live    # real APIs
uv run ruff check .

Tools live in src/jabama_mcp/search.py, stay.py, info.py, tours.py and events.py; each is a typed async function with a docstring that tells the agent when to use it. Issues and PRs are welcome, especially new tools and fixes for API changes.

Releases: bump the version in pyproject.toml and server.json, then push a v* tag. GitHub Actions tests, publishes to PyPI and the MCP Registry, and creates the GitHub Release.

Related servers

• Otaghak MCP server for villa, cottage and apartment stays
• Flytoday MCP server for flights, hotels and villas
• MrBilit MCP server for flights, trains, buses and hotels
• All servers: awesome-iran-mcp, the catalog of Iranian MCP servers

If this saves you clicks, a star helps others find it.

Disclaimer

Unofficial and not affiliated with or endorsed by Jabama. It uses the public endpoints of the jabama.com, jabama.tours and jabama.events websites, which can change without notice. Please keep request rates reasonable.

License

MIT