flytoday-mcp
Advanced tools
Unofficial read-only MCP server for Flytoday: cheapest domestic and international flights, hotels, stays, trains and buses in Iran, with fare rules and exact prices.
Let your AI agent plan trips on Flytoday (فلای‌تودی), in Iran and abroad.
An unofficial, read-only MCP server for Flytoday, the Iranian online travel agency:
cheapest domestic and international flights, trains and buses, fare rules and baggage, hotels and villas with exact prices, plus CIP lounges, eSIMs and visas, from Claude, Cursor or Copilot.
For AI agents · Why · What it can do · Quick start · Tools · Good to know · FAQ · Configuration · فارسی · Development
uvx flytoday-mcp or claude mcp add flytoday -- uvx flytoday-mcp. Transport: stdio. Needs Python 3.10+ and uv.FLYTODAY_MCP_PROXY (HTTP proxy, or a comma-separated list), only if your network cannot reach flytoday.ir or your IP is rate limited. System proxy settings are ignored.readOnlyHint: true.ft_. Start with a find tool (ft_find_airport, ft_find_hotel_place, ft_find_station, ft_find_bus_city) to get ids. Flights: ft_flight_calendar → ft_search_flights → ft_flight_details. Hotels: ft_search_hotels → ft_hotel. Villas: ft_search_stays → ft_stay.*_toman (visa and some activity prices in a foreign currency, see price_currency); dates Gregorian YYYY-MM-DD, past dates are rejected. search_id and fare_source_code expire after about 15 minutes.server.json; catalog of all Iranian MCP servers: iran-mcp (TOOLS.md, servers.json, llms.txt).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.
Example prompts:
You need uv. No API key or account.
claude mcp add flytoday -- uvx flytoday-mcp
If Flytoday does not answer from your network, add a proxy:
claude mcp add flytoday -e FLYTODAY_MCP_PROXY=http://127.0.0.1:8080 -- uvx flytoday-mcp
Settings → Developer → Edit Config, then add:
{
"mcpServers": {
"flytoday": { "command": "uvx", "args": ["flytoday-mcp"] }
}
}
Need a proxy? Add "env": { "FLYTODAY_MCP_PROXY": "http://127.0.0.1:8080" } next to args.
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": {
"flytoday": { "type": "stdio", "command": "uvx", "args": ["flytoday-mcp"] }
}
}
codex mcp add flytoday -- uvx flytoday-mcp
Or in ~/.codex/config.toml:
[mcp_servers.flytoday]
command = "uvx"
args = ["flytoday-mcp"]
Add to ~/.gemini/settings.json:
{
"mcpServers": {
"flytoday": { "command": "uvx", "args": ["flytoday-mcp"] }
}
}
Add the Claude Desktop block to ~/.codeium/windsurf/mcp_config.json.
It's a standard stdio MCP server: run uvx flytoday-mcp, or pip install flytoday-mcp and run flytoday-mcp.
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).
| Tool | What it does |
|---|---|
ft_find_airport | Finds IATA codes for Iranian and international cities and airports, or lists the popular ones |
ft_search_flights | Searches one-way or round-trip flights with filters, sorting and paging, in Toman, with fare_source_code and search_id |
ft_flight_calendar | Shows the cheapest fare per departure day around a date and marks the cheapest day |
ft_flight_details | Gives the refund and change rules, baggage and international entry notes of one fare |
| Tool | What it does |
|---|---|
ft_find_hotel_place | Find city, region and hotel ids for hotels, and region codes for villa stays; popular places when empty |
ft_search_hotels | Priced hotels of a city or region for dates: whole-stay and per-night Toman, stars, score, refundable, meal |
ft_hotel | One hotel: room and meal offers with price, rooms left and cancellation terms, room details, basics |
ft_hotel_reviews | Guest reviews of a hotel with score, text, pros and cons |
ft_search_stays | Villas and apartments in Iran for dates, cheapest first, Toman per night and total |
ft_stay | One villa or apartment: details, price calendar with blocked days, reviews |
| Tool | What it does |
|---|---|
ft_find_station | Train station codes by city name, or the popular stations |
ft_search_trains | Trains between two stations on a date: company, class, times, seats left, price per adult |
ft_train_calendar | Cheapest train price per day for the next ~16 days, sold-out days flagged |
ft_train_stops | Stops and times of one train, plus class amenities and meals |
| Tool | What it does |
|---|---|
ft_find_bus_city | Bus city ids by name, or the popular cities |
ft_bus_calendar | Cheapest bus seat price per day for the next weeks (the site's price strip) |
ft_search_buses | Buses between two cities on a date: company, terminals, type, seats left, price per seat |
| Tool | What it does |
|---|---|
ft_cip | CIP / VIP airport lounge prices and add-ons at IKA and MHD for a date and passengers, per passport nationality |
ft_esim_plans | eSIM data plans for a country (GB, days, price in Toman), cheapest first |
ft_visa | Visa country list with from-prices, or one country's prices, documents and processing time |
ft_activities | Tours, tickets and activities in a destination with from-prices for a date range |
ft_activity | One activity: description, options, prices and cheapest days |
All 22 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
▼
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. Requests go out through a
Chrome-impersonating HTTP client, at most two at a time with a short random pause, and failed calls (timeouts, 5xx,
429) are retried up to twice. Static lookup lists (CIP airports, eSIM countries, visa countries) are cached for 6 hours.
*_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).YYYY-MM-DD; past dates are rejected. Times are local to the place.airline (English name) and airline_fa (Persian name, when the API has one).ft_hotel, ft_stay) carry image, the cover photo, built like the site as
<cdn>/<id>/main.jpg (the API has no image field).search_id) instead of searching again; the tools never loop searches.search_id and fare_source_code are valid for about 15 minutes.ft_search_trains retries three times, then says so.FLYTODAY_MCP_PROXY if your network cannot reach flytoday.ir (see Configuration).flytoday-mcp is an unofficial MCP server for Flytoday: it exposes the public gateway of the flytoday.ir website
as 22 read-only tools, so an agent can compare flights, hotels, villas, trains and buses.
Install it with uvx flytoday-mcp (see Quick start), then ask in Persian or English, for example
"cheapest day to fly Tehran to Istanbul next month, and the refund rules of that fare".
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.
Usually not: the website's gateway answers from Iran and from abroad. If your network cannot reach
www.flytoday.ir, or your IP is rate limited, set FLYTODAY_MCP_PROXY to an HTTP proxy (or a comma-separated list, used one at a time). System proxy variables
(HTTPS_PROXY, ...) are ignored on purpose.
No, and that's deliberate. It has no login and never holds a seat, reserves, orders or pays. The agent finds the best option; you book on flytoday.ir.
Flytoday limits searches per IP. Wait (the hotel captcha block can last an hour or more) or use another network
through FLYTODAY_MCP_PROXY. Calendars, details, reviews and stay searches are not limited.
If Flytoday serves a bot-check page instead, install the browser extra (pip install flytoday-mcp[browser], or
uvx --with patchright==1.63.0 flytoday-mcp) and run patchright install chromium; the server then clears it once
in a headless browser.
The site's seat map comes from the first call of its checkout flow. It is left out until it is clear that the call holds nothing.
Toman. Flytoday's API sends Rial and the tools divide by 10; fields are named *_toman. Visa and some activity
prices are in a foreign currency, shown in price_currency.
npx @modelcontextprotocol/inspector uvx flytoday-mcp
| Variable | Default | Meaning |
|---|---|---|
FLYTODAY_MCP_PROXY | unset | Optional HTTP proxy, e.g. http://user:pass@host:port; a comma-separated list is used one at a time (next after a block or connect error). System proxy settings are ignored |
flytoday-mcp یک سرور MCP غیررسمی و فقط‌خواندنی برای فلای‌تودی (flytoday.ir)، آژانس مسافرتی آنلاین ایران، است. این سرور به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه می‌دهد در فلای‌تودی ارزان‌ترین پرواز داخلی و خارجی، قطار یا اتوبوس را برای یک روز یا یک ماه پیدا کند، قوانین استرداد و بار مجاز را ببیند و هتل‌ها و ویلاها را با قیمت دقیق مقایسه کند؛ همچنین قیمت CIP، سیم‌کارت eSIM و ویزا را می‌گوید.
چه کارهایی می‌کند
نکته‌ها
FLYTODAY_MCP_PROXY را روی یک پراکسی HTTP بگذارید.نصب (اول uv را نصب کنید). در Claude Code:
claude mcp add flytoday -- uvx flytoday-mcp
در Claude Desktop، Cursor و بقیه برنامه‌ها همان تنظیم بخش Quick start را بگذارید.
نمونه پرسش‌ها
git clone https://github.com/sepehr071/flytoday-mcp && cd flytoday-mcp
uv sync
uv run python -m pytest # offline, against recorded responses
uv run python -m 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.
If this saves you clicks, a star helps others find it.
Unofficial and not affiliated with or endorsed by Flytoday. It is read-only and uses the public endpoints of the flytoday.ir website, 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 Flytoday: cheapest domestic and international flights, hotels, stays, trains and buses in Iran, with fare rules and exact prices.
The pypi package flytoday-mcp receives a total of 550 weekly downloads. As such, flytoday-mcp popularity was classified as not popular.
We found that flytoday-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.