Flytoday README

✈️ flytoday-mcp: Flytoday MCP server for AI agents

Unofficial, read-only MCP server for Flytoday (فلای تودی): let your AI agent plan trips in Iran and abroad.
Find the cheapest domestic or international flight, train or bus on a date or over a month, read fare rules and baggage,
compare hotels and villas with exact prices, and price CIP lounges, eSIMs and visas, all from Claude, Cursor or Copilot.

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

For AI agents

• What: unofficial, read-only MCP server for Flytoday (فلای تودی), an Iranian travel site: domestic and international flights, hotels in Iran and abroad, villas, trains, buses, CIP lounges, eSIMs and visas. Queries work in Persian and English; prices are in Toman.
• Install: claude mcp add flytoday -- uvx flytoday-mcp (stdio transport; needs Python 3.10+ and uv).
• Auth: none, no API key. Optional FLYTODAY_MCP_PROXY (HTTP proxy), only if your network cannot reach flytoday.ir or your IP is rate limited.
• Access: read-only. No login, seat hold, booking or payment, so no confirmation is needed before calling tools.
• Tools: 22, all prefixed ft_*. Start with a find tool (ft_find_airport, ft_find_hotel_place, ft_find_station, ft_find_bus_city), then a calendar such as ft_flight_calendar → ft_search_flights → ft_flight_details. Hotels: ft_search_hotels → ft_hotel.
• Use when: comparing flights, hotels, villas, trains or buses, or pricing a CIP lounge, eSIM or visa.
• Do not use when: you need to book or pay (the user does that on flytoday.ir). Searches are rate limited per IP, so prefer calendars and paging over repeated searches.
• Output: compact JSON. Prices in Toman in *_toman fields (visa and some activities in a foreign currency), dates Gregorian YYYY-MM-DD. search_id and fare_source_code expire after about 15 minutes.
• Machine-readable: server.json; catalog of all Iranian MCP servers: awesome-iran-mcp (TOOLS.md, servers.json, ).

Why use Flytoday MCP

Flytoday (flytoday.ir, فلای تودی) sells domestic and international flights, hotels, villas, trains, buses, CIP lounges, eSIMs and visas. Comparing "which day, plane or train or bus, which hotel" still means many page loads. An agent with flytoday-mcp does it in one go:

You: Cheapest way from Tehran to Mashhad around 20 October?

Agent: calls ft_flight_calendar(origin="THR", destination="MHD", date="2026-10-21", window="week"), ft_train_calendar(origin="1", destination="191")

Mode	Cheapest day	Price (Toman)
Flight	2026-10-20, airline IRZ	11,056,700
Train	2026-10-20 (and most days that week)	760,000

The train is far cheaper; want me to list that day's trains with ft_search_trains?

_{Real tool output from 2026-10-07; 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, airline, direct, charter/system and time filters
• 📅 Cheapest day for flights (+-15 days), trains (~16 days) and buses (~6 weeks)
• 📜 Fare details: refund and change rules, baggage, international entry notes
• 🏨 Hotels in Iran and abroad: priced search, room and meal offers with cancellation terms, guest reviews
• 🏡 Villas and apartments in Iran: price per night and total, per-date calendar with blocked days
• 🚆🚌 Trains and buses: classes, seats left, stops, amenities, VIP and sleeper buses
• 🛂 Extras: CIP lounges at IKA and MHD, eSIM data plans per country, visa prices and documents, tours and tickets
• 🔒 Read-only by design: no login, no seat hold, no booking, no payment

Quick start

You need uv.

claude mcp add flytoday -- uvx flytoday-mcp

claude mcp add flytoday -e FLYTODAY_MCP_PROXY=http://127.0.0.1:8080 -- uvx flytoday-mcp

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

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

Then just ask:

• "Cheapest day to fly Tehran to Istanbul next month, and the refund rules of that fare?"
• "Hotels in Mashhad for 2 nights from the 21st, cheapest first, with free cancellation."
• "A villa in Ramsar for 4 people next weekend under 5 million Toman a night."
• ارزان‌ترین اتوبوس VIP تهران به اصفهان دوشنبه بعد؟

How it works

  AI agent  (Claude, Cursor, Copilot, ...)
      │
      │  MCP over stdio
      ▼
  flytoday-mcp  (runs on your machine)
      │
      │  HTTPS (optional proxy)
      ▼
  www.flytoday.ir/api/gateway  ──▶  api.flytoday.ir, placesearch.flytoday.ir

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

Tools

Each vertical has its own ids, taken from its find tool: IATA codes for flights (THR, MHD, IST), hotel city_id / region_code, stay region_code, train station codes (Tehran 1, Mashhad 191), 4-digit bus city ids (Tehran 0001, Isfahan 0002).

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, in fields named *_toman (the API sends Rial; values are divided by 10). Flight price_toman is per adult and total_toman the whole party; hotel price_toman is the whole stay (with per_night_toman); stays give price_per_night_toman and total_toman; trains per adult; buses per seat. Visa and some activity prices are in a foreign currency (price_currency).
• Dates in and out are Gregorian YYYY-MM-DD; past dates are rejected. Times are local to the place.
• Flights give airline (English name) and airline_fa (Persian name, when the API has one).
• Hotels and stays (search rows, ft_hotel, ft_stay) carry image, the cover photo, built like the site as <cdn>/<id>/main.jpg (the API has no image field).
• Searches are rate limited per IP by Flytoday: about 15 flight/train/bus searches, and hotel search asks for a captcha after about 12 searches in 10 minutes (blocked for an hour or more). Use the calendars and paging (search_id) instead of searching again; the tools never loop searches.
• Ids expire: search_id and fare_source_code are valid for about 15 minutes.
• Sales windows: trains open about 16 days ahead. An empty result often just means "not on sale yet".
• When the rail companies' link is down, Flytoday answers HTTP 599; ft_search_trains retries three times, then says so.

FAQ

npx @modelcontextprotocol/inspector uvx flytoday-mcp

Configuration

Safety

• Read-only: no login or OTP, no seat hold, reservation, order, payment, refund, review or bookmark. The only POSTs are searches and price lookups the site itself makes before booking.
• At most two requests at a time, and no tool repeats a search in a loop.

فارسی: سرور MCP فلای‌تودی

claude mcp add flytoday -- uvx flytoday-mcp

Development

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

Tools live in src/flytoday_mcp/flights.py, hotels.py, trains.py, buses.py and extras.py; each is a typed async function with a docstring that tells the agent when to use it. Issues and PRs are welcome.

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

• MrBilit MCP server for flights, trains, buses, taxis and hotels
• Jabama MCP server for villas, tours and events
• Otaghak MCP server for villa, cottage and apartment stays
• 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 Flytoday. It uses the public endpoints of the flytoday.ir website, which can change without notice. Please keep request rates reasonable.

License

MIT