mrbilit-mcp: MrBilit MCP server for AI agents

Let your AI agent plan trips in Iran with MrBilit (مستربلیط).
An unofficial, read-only MCP server for MrBilit, an Iranian travel site for flights, trains, buses, taxis and hotels:
find the cheapest option on a date or over a month, see seats, baggage and refund rules, and compare hotel rooms with exact prices, 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 · Disclaimer · License

For AI agents

• What: unofficial, read-only MCP server for MrBilit (مستربلیط), an Iranian travel site: flights, trains, intercity buses, private taxis and hotels. Queries work in Persian and English; prices are in Toman.
• Install: claude mcp add mrbilit -- uvx mrbilit-mcp (stdio transport; needs Python 3.10+ and uv).
• Auth: none, no API key or account. Optional MRBILIT_MCP_PROXY (HTTP proxy), only if your network cannot reach MrBilit's API servers.
• Access: read-only (all 22 tools carry readOnlyHint: true). No login, seat hold, booking or payment, so no confirmation is needed before calling tools.
• Tools: 22, all prefixed mb_*. Call mb_find_place first for the codes every search takes, then a price calendar (mb_flight_price_calendar, mb_train_price_calendar, mb_bus_price_calendar) → mb_search_flights / mb_search_trains / mb_search_buses → mb_flight_fare_details, mb_train_price or mb_bus_seats. Hotels: mb_search_hotels → mb_hotel_rooms.
• Use when: comparing the cheapest plane, train, bus or taxi between Iranian cities, or hotel prices, with seats and refund rules.
• Do not use when: you need to book, hold a seat or pay (the user does that on mrbilit.com).
• Output: compact JSON. Prices in Toman in *_toman fields, dates Gregorian YYYY-MM-DD, ratings 0-5. Ids such as flight_id, class_id and bus_id come from a fresh search and expire.
• Machine-readable: server.json; catalog of all Iranian MCP servers: awesome-iran-mcp (TOOLS.md, servers.json, llms.txt).

Why

MrBilit (mrbilit.com, مستربلیط) sells flights, trains, intercity buses, private taxis and hotels in one place, but each one has its own search, calendar and rules. Comparing "plane or train or bus, which day, which seat" means a dozen page loads. An agent with mrbilit-mcp does it in one go:

You: Cheapest way to get from Tehran to Mashhad on 20 October?

Agent: calls mb_search_flights(origin="THR", destination="MHD", date="2026-10-20"), mb_train_price_calendar(origin=1, destination=191), mb_search_buses(origin=11320000, destination=31310000, date="2026-10-20", sort="cheapest")

Mode	Cheapest option	Departs	Price (Toman)
Bus	Peyk Saba VIP, Tehran South terminal, 17 seats left	21:00, arrives 09:00	1,313,000
Train	cheapest seat of the day (price calendar)	list with mb_search_trains	760,000
Flight	Mehr Air MEH 4200, Mehrabad, 2 seats left	08:30, arrives 09:30	11,856,000

The train is cheapest; want me to list that day's trains and free seats with mb_search_trains?

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

What it can do

• Flights: domestic and international, one-way or round trip, party prices, cabin/airline/direct/time filters
• Cheapest day for flights, trains and buses over weeks, and the cheapest nights of a hotel
• Trains: every class with free seats, exact price for children, infants or a whole compartment, every stop
• Buses and taxis: terminals, companies, VIP, seat maps with women/men seats, private door-to-door cars
• Alternatives when trains are full: one-change trips, nearby stations, bus routes and airports
• Hotels: available stays with prices, every hotel of a city, guest ratings and reviews, rooms and exact prices
• Context: current site notices, official refund and baggage rules, help-center guides, route guides
• Read-only by design: no login, no seat hold, no booking, no payment

Example prompts:

• "Cheapest day to fly Tehran to Kish in the next month, and the baggage on that flight?"
• "Train from Tehran to Mashhad next Friday for 2 adults and a child: which classes have seats and what's the total?"
• "4-star hotels in Shiraz for 3 nights from the 20th under 3 million Toman a night, with their reviews."
• "The Tehran to Tabriz train is full on Thursday. What else gets me there?"
• ارزان‌ترین اتوبوس VIP تهران به اصفهان فردا شب و صندلی‌های خالی آن؟
• ارزان‌ترین روز برای پرواز تهران به کیش در ماه آینده کدام است؟
• هتل‌های ۴ ستاره مشهد برای سه شب با قیمت دقیق اتاق‌ها را مقایسه کن.

Quick start

You need uv. No API key or account.

claude mcp add mrbilit -- uvx mrbilit-mcp

claude mcp add mrbilit -e MRBILIT_MCP_PROXY=http://127.0.0.1:8080 -- uvx mrbilit-mcp

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

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

codex mcp add mrbilit -- uvx mrbilit-mcp

[mcp_servers.mrbilit]
command = "uvx"
args = ["mrbilit-mcp"]

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

Then ask the prompts above, in Persian or English.

Tools

Every search takes the codes from mb_find_place: IATA codes for flights (THR, MHD, ISTALL), station ids for trains (Tehran 1, Mashhad 191), 8-digit city ids for buses and taxis (Tehran 11320000), slugs for hotels (mashhad, mashhad/enghelab).

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

How it works

  AI agent  (Claude, Cursor, Copilot, ...)
      │
      │  MCP over stdio
      ▼
  mrbilit-mcp  (runs on your machine)
      │
      │  HTTPS (REST, optional proxy)
      ├──────▶  flight.atighgasht.com, train.mrbilit.com, masir.mrbilit.com, bus.mrbilit.ir, hotel.mrbilit.ir
      └──────▶  content.mrbilit.ir, directus.mrbilit.ir, mrbilit.com (site lists, magazine)

mrbilit-mcp runs locally and calls the same public endpoints the mrbilit.com website uses. There's no hosted server in between, no API key, and nothing about you is sent anywhere else.

Good to know

• Prices are in Toman in every tool (the API sends Rial; values are divided by 10), always in fields named *_toman. Flight price_toman is per adult and total_toman the whole party; trains per adult; buses per seat; taxis per car; hotels the whole stay for one room.
• Dates in and out are Gregorian YYYY-MM-DD; past dates are rejected. Times are local to the place: a flight time at a foreign airport is that airport's local time, although the API puts +03:30 on every flight time.
• Ratings are 0–5; null means not rated. The site shows hotel ratings ×2 out of 10.
• Ids expire: flight_id, class_id and bus_id come from a fresh search.
• Sales windows: trains open about 18 days ahead, buses about a month. An empty result often just means "not on sale yet".
• Round trips: domestic flights are two separate tickets (two lists); international round trips are priced as one package.
• Hotel prices do not depend on the guest count: pick rooms whose sleeps fits, and add rooms up for a group.
• Domestic airports and train stations come from the site's own bundled lists, fetched once per run with a copy shipped in the package as a fallback.
• Bus and taxi cities come from MrBilit's live city lists, which are fresher than the bundled copies.
• Untrusted text: reviews (cut at 400 characters), rules, notices and guides are site content; the server tells the agent to treat them as data, not instructions.
• What it does not do: no login or OTP, seat hold, booking, payment, wallet, refund, coupon, price alert or review posting. You book on mrbilit.com.
• Reply size: results are compact JSON, kept to roughly 15 KB by default.
• Request rate: at most two requests at a time with a short random delay, because the API hosts share one server.

FAQ

npx @modelcontextprotocol/inspector uvx mrbilit-mcp

Configuration

Safety and network

• Read-only: no login or OTP, no seat hold, reservation, order, payment, wallet, price alert or review posting. The only POSTs are searches and price lookups the site itself makes before booking.
• Admin fields (created_by, updated_by) of the content CMS are never passed through.
• Sends a real Chrome TLS fingerprint and headers (via curl_cffi) and at most two requests at a time with a short random delay, since the API hosts share one server.
• If MrBilit serves a bot-check page, the server can clear it in a headless browser: pip install mrbilit-mcp[browser], then patchright install chromium.

فارسی: سرور MCP مستربلیط

claude mcp add mrbilit -- uvx mrbilit-mcp

Development

git clone https://github.com/sepehr071/mrbilit-mcp && cd mrbilit-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 API (set MRBILIT_MCP_PROXY if needed)
uv build

Tools live in src/mrbilit_mcp/places.py, flights.py, trains.py, buses.py, hotels.py and content.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

• awesome-iran-mcp: catalog of all Iranian-service MCP servers
• flytoday-mcp for flights, hotels, trains and buses on Flytoday
• jabama-mcp for villas, tours and events on Jabama
• otaghak-mcp for villa, cottage and apartment stays on Otaghak

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

Disclaimer

Unofficial and not affiliated with or endorsed by MrBilit. It is read-only and uses the public endpoints of the mrbilit.com website, which can change without notice. Please keep request rates reasonable.

License

MIT