✈️ mrbilit-mcp

Let your AI agent plan trips in Iran with MrBilit.
Find the cheapest flight, train, bus or private taxi on a date or over a month, see seats, baggage and refund rules,
and compare hotels with exact room prices, all from Claude, Cursor or Copilot.

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

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 that day		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

Quick start

You need uv.

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"] }
  }
}

Then just ask:

• "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."
• ارزان‌ترین اتوبوس VIP تهران به اصفهان فردا شب و صندلی‌های خالی آن؟

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.

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.

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.

FAQ

npx @modelcontextprotocol/inspector uvx mrbilit-mcp

Configuration

Safety

• 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.
• Always sends a browser User-Agent and at most two requests at a time, since the API hosts share one server.

فارسی

claude mcp add mrbilit -- uvx mrbilit-mcp

Development

git clone https://github.com/sepehr071/mrbilit-mcp && cd mrbilit-mcp
uv sync
uv run pytest            # offline, against recorded responses
uv run pytest -m live    # real API (set MRBILIT_MCP_PROXY if needed)
uv run ruff check .

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.

Disclaimer

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

License

MIT