jabama-mcp
Advanced tools
Unofficial read-only MCP server for Jabama: search villas and stays with exact prices, group tours, events and theater tickets.
Unofficial, read-only MCP server for Jabama (جاباما): let your AI agent plan stays in Iran.
Search villas, suites and eco-lodges on Jabama with the exact price for your dates and guests, read rules and reviews,
and find group tours on Jabama Tours, events and theater seats on Jabama Events, all from Claude, Cursor or Copilot.
For AI agents · Why · What it can do · Quick start · Tools · How it works · Good to know · FAQ · Configuration · فارسی · Development · Related servers
uvx jabama-mcp or claude mcp add jabama -- uvx jabama-mcp. Transport: stdio. Needs uv (Python 3.10+).JABAMA_MCP_PROXY (HTTP proxy URL, or a comma-separated list) if Jabama blocks your network; system proxy settings are ignored.jb_. Stays: jb_find_destination (or jb_parse_request for free text) → jb_search_stays → jb_stay_calendar → jb_price_quote. Tours: jb_tour_places → jb_search_tours → jb_tour. Events: jb_event_filters → jb_search_events → jb_event → jb_event_seats. Theater: jb_theaters → jb_theater.YYYY-MM-DD (convert Jalali first), times Tehran local, ratings 0-5 (null = not rated).328353) between stay tools; tours use an 8-digit id; events and plays use the id in their page URL.server.json; catalog of all Iranian MCP servers: iran-mcp (TOOLS.md, servers.json, llms.txt).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.
Every reply is compact JSON, so it does not flood the agent's context.
Example prompts:
You need uv. No API key or account.
claude mcp add jabama -- uvx jabama-mcp
Settings → Developer → Edit Config, then add:
{
"mcpServers": {
"jabama": { "command": "uvx", "args": ["jabama-mcp"] }
}
}
Click Install in Cursor above, or add the Claude Desktop block to ~/.cursor/mcp.json (or .cursor/mcp.json in a project).
Click Install in VS Code above, or add to .vscode/mcp.json:
{
"servers": {
"jabama": { "type": "stdio", "command": "uvx", "args": ["jabama-mcp"] }
}
}
codex mcp add jabama -- uvx jabama-mcp
Or in ~/.codex/config.toml:
[mcp_servers.jabama]
command = "uvx"
args = ["jabama-mcp"]
Add to ~/.gemini/settings.json:
{
"mcpServers": {
"jabama": { "command": "uvx", "args": ["jabama-mcp"] }
}
}
Add the Claude Desktop block to ~/.codeium/windsurf/mcp_config.json.
It is a standard stdio MCP server: run uvx jabama-mcp, or pip install jabama-mcp and run jabama-mcp.
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.
| Tool | What it does |
|---|---|
jb_find_destination | Persian place name → ready search arguments (city, area, landmark, complex) |
jb_parse_request | Free-text request → search arguments, using Jabama's AI parser |
jb_search_stays | Search stays for dates and guests with filters, whole-stay prices, sorting |
jb_categories | Themed lists (special pool, luxury, cheap, jungle, pet friendly, last-minute, ...) |
| Tool | What it does |
|---|---|
jb_stay | Capacity, beds, rules, amenities and missing ones, cancellation policy, host, review scores |
jb_stay_calendar | Free nights and nightly prices with weekend and holiday flags (~76 days) |
jb_price_quote | Exact payable amount for dates and guests, night by night; unit options for complexes |
jb_similar_stays | Similar stays nearby (priced for your dates) and other units of the same property |
jb_reviews | Guest reviews, newest or best/worst first, with host replies |
jb_host | A host's listings and reviews across all of them |
| Tool | What it does |
|---|---|
jb_help | Jabama's rules: cancellation, refunds, payment, tax (help center + support answers) |
jb_travel_guide | Jabama magazine travel guides for a destination |
| Tool | What it does |
|---|---|
jb_search_events | Events and experiences by city, category, date, price and rating |
jb_event | One event: details, address, rules, sessions with seats left, reviews, organizer |
jb_event_seats | Free seats of a seated session by section and row, with section prices |
jb_theaters | Theater plays on sale: venue, from-price, rating, cast |
jb_theater | One play: showtimes with live seats left; free seats of a showtime |
jb_event_filters | Event cities and categories with counts |
| Tool | What it does |
|---|---|
jb_search_tours | Tours by place, dates, category, tags, duration, price, difficulty, rating |
jb_tour | One tour: departures with free seats and package prices, day plan, inclusions, cancellation, reviews |
jb_tour_places | Place name → place id for the tour search |
All 21 tools are annotated readOnlyHint: true and return compact structured JSON, so they don't flood the agent's context.
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.
Jabama's web firewall rejects ordinary HTTP libraries, so requests go out through a Chrome-impersonating client
(TLS and headers). It sends at most 2 requests at a time with a short random delay, retries a failed request up to
twice, and only reads. If the firewall serves a bot-check page, an optional headless-browser fallback can clear it
(see the FAQ).
pricing is per_unit).total_price); cheapest_night is the cheapest single night, not the average. Without dates a search prices one default night.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.guests is everyone who stays.YYYY-MM-DD (1405-07-28 = 2026-10-20); times are Tehran local. Stays can be quoted for about the next 76 days. Jalali-looking dates (year before 1900) are rejected instead of silently returning no results.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.city-ramsar also returns nearby towns (Tonekabon); keyword all with the city filter returns the city alone.instant_booking: false means the host must accept first. instant_only keeps only instant listings.jb_tour has correct free seats; tour lists count seats once per package. Tour text search is loose (a Kish query can return Yazd tours), so search by place id from jb_tour_places.seats_left still work.null means not rated yet. Stay reviews carry only a Jalali month, not a date.JABAMA_MCP_PROXY sets an HTTP proxy for every request; system proxy variables are ignored on purpose.jabama-mcp is an unofficial MCP server for Jabama: it exposes the public endpoints of the Jabama websites as 21
read-only tools, so an agent can search stays, tours and events and get exact prices.
Install it with uvx jabama-mcp (see Quick start), then ask in Persian or English, for example
"cheapest villa with a pool in Ramsar for 6 people next weekend, with the exact total".
It is unofficial and MIT licensed, so free to use. It is read-only: no login, no API key, no booking or payment, and it runs on your machine.
No, and that's deliberate. It has no login and never calls booking, order, payment, seat-hold or wallet endpoints.
jb_price_quote only asks for a price. The agent finds the best option; you book on the site.
jb_price_quote uses the same read-only price quote the listing page shows, in Toman, for your dates and guests.
It shows no tax line; Jabama's help center says 1.5% tax is added when booking. Prices change all the time.
Usually nothing is free for those dates with those filters, or the dates are past the ~76-day calendar. Try other dates or fewer filters. Dates must be Gregorian; the server rejects Jalali-looking dates instead of searching.
No geo block was seen: direct calls and calls through a proxy in Turkey both worked (2026-10-04). Cloud servers
were not tested; if Jabama blocks one, set JABAMA_MCP_PROXY.
Jabama's web firewall rejects requests that don't look like a browser; the server already presents itself as Chrome
(TLS and headers). If the firewall serves a bot-check page, install the browser extra (pip install jabama-mcp[browser],
then patchright install chromium). If it still happens, wait a minute, turn off a VPN, or set JABAMA_MCP_PROXY. Normal system proxy
variables are ignored on purpose, because direct calls are the fastest.
The theater seat map comes live from Jabama's ticketing partner, which sometimes refuses for a while. The showtimes and
seats_left still work; try the seat map again later or for another showtime.
uvx is not foundUse the full path to uvx (where uvx on Windows, which uvx on macOS/Linux) as command.
npx @modelcontextprotocol/inspector uvx jabama-mcp
| Variable | Default | Meaning |
|---|---|---|
JABAMA_MCP_PROXY | unset | Optional HTTP proxy URL for every request, e.g. http://user:pass@host:port; system proxy settings are ignored. A comma-separated list is used one at a time: the next proxy takes over when one is blocked or cannot connect |
No other variables, and no API key.
jabama-mcp یک سرور MCP غیررسمی و فقط‌خواندنی برای جاباما (jabama.com، سایت اجاره کوتاه‌مدت ویلا و اقامتگاه در ایران) است. به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه می‌دهد در جاباما ویلا، سوئیت و اقامتگاه بوم‌گردی پیدا کند، قیمت دقیق را برای تاریخ و تعداد نفرات شما بگیرد، قوانین و نظرات را بخواند و تورهای گروهی (جاباما تورز)، رویدادها و صندلی‌های خالی تئاتر (جاباما ایونتس) را هم پیدا کند.
چه کارهایی می‌کند
نکته‌ها
JABAMA_MCP_PROXY را روی یک پراکسی HTTP بگذارید.نصب (اول uv را نصب کنید). در Claude Code:
claude mcp add jabama -- uvx jabama-mcp
در Claude Desktop، Cursor و بقیه برنامه‌ها همان تنظیم بخش Quick start را بگذارید.
نمونه پرسش‌ها
git clone https://github.com/sepehr071/jabama-mcp && cd jabama-mcp
uv sync
uv run ruff check . && uv run ruff format --check .
uv run python -m pytest -q # offline, against recorded responses
uv run python -m pytest -m live -q # real APIs
uv build
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.
If this saves you clicks, a star helps others find it.
Unofficial and not affiliated with or endorsed by Jabama. It is read-only and uses the public endpoints of the jabama.com, jabama.tours and jabama.events websites, which can change without notice. Please keep request rates reasonable.
Built and maintained by Sepehr Radmard (سپهر رادمرد). Connect on LinkedIn or follow @sepehr071 on GitHub for more MCP servers for Iranian websites, all listed in iran-mcp. If this saves you time, a star on the repo helps other people find it.
FAQs
Unofficial read-only MCP server for Jabama: search villas and stays with exact prices, group tours, events and theater tickets.
The pypi package jabama-mcp receives a total of 602 weekly downloads. As such, jabama-mcp popularity was classified as not popular.
We found that jabama-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Threat Research
/Security News
Socket uncovered secret-stealing workflows that ran in LiteLLM’s GitHub repository 11 days before the supply chain attack on PyPI and Docker.
Security News
Cloudflare introduces tsrs, a Rust port of TypeScript’s compiler promising faster checks and lower memory use, with the TypeScript team’s help.
Security News
The PHP Foundation says Chainguard broke a security embargo ahead of critical RCE patches, as leaks disrupted the coordinated release.