flytoday-mcp

<!-- mcp-name: io.github.sepehr071/flytoday-mcp -->

<div align="center">

<img src="https://raw.githubusercontent.com/sepehr071/flytoday-mcp/main/.github/banner.png" alt="flytoday-mcp: unofficial Flytoday MCP server for Claude, Cursor and Copilot" width="100%">

# ✈️ 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.**<br>
Find the cheapest domestic or international flight, train or bus on a date or over a month, read fare rules and baggage,<br>
compare hotels and villas with exact prices, and price CIP lounges, eSIMs and visas, all from Claude, Cursor or Copilot.

[![PyPI](https://img.shields.io/pypi/v/flytoday-mcp?color=2563eb)](https://pypi.org/project/flytoday-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/flytoday-mcp)](https://pypi.org/project/flytoday-mcp/)
[![CI](https://github.com/sepehr071/flytoday-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sepehr071/flytoday-mcp/actions/workflows/ci.yml)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.sepehr071%2Fflytoday--mcp-7c3aed)](https://registry.modelcontextprotocol.io/?q=flytoday-mcp)
[![License: MIT](https://img.shields.io/badge/license-MIT-16a34a)](https://github.com/sepehr071/flytoday-mcp/blob/main/LICENSE)

[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=flytoday&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJmbHl0b2RheS1tY3AiXX0=)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_flytoday--mcp-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=flytoday&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22flytoday-mcp%22%5D%7D)

[Quick start](#quick-start) · [What it can do](#what-it-can-do) · [Tools](#tools) · [FAQ](#faq) · [فارسی](#فارسی)

</div>

---

## 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](https://docs.astral.sh/uv/getting-started/installation/)).
- **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`](https://github.com/sepehr071/flytoday-mcp/blob/main/server.json); catalog of all Iranian MCP servers: [awesome-iran-mcp](https://github.com/sepehr071/awesome-iran-mcp) ([TOOLS.md](https://github.com/sepehr071/awesome-iran-mcp/blob/main/TOOLS.md), [servers.json](https://github.com/sepehr071/awesome-iran-mcp/blob/main/servers.json), [llms.txt](https://github.com/sepehr071/awesome-iran-mcp/blob/main/llms.txt)).

## 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`?

<sub>Real tool output from 2026-10-07; prices and seats change all the time. Prices are in Toman.</sub>

## 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](https://docs.astral.sh/uv/getting-started/installation/).

<details open>
<summary><b>Claude Code</b></summary>

```bash
claude mcp add flytoday -- uvx flytoday-mcp
```

If Flytoday does not answer from your network, add a proxy:

```bash
claude mcp add flytoday -e FLYTODAY_MCP_PROXY=http://127.0.0.1:8080 -- uvx flytoday-mcp
```
</details>

<details>
<summary><b>Claude Desktop</b></summary>

Settings → Developer → Edit Config, then add:

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

Need a proxy? Add `"env": { "FLYTODAY_MCP_PROXY": "http://127.0.0.1:8080" }` next to `args`.
</details>

<details>
<summary><b>Cursor</b></summary>

Click **Install in Cursor** above, or add the Claude Desktop block to `~/.cursor/mcp.json`.
</details>

<details>
<summary><b>VS Code (Copilot agent mode)</b></summary>

Click **Install in VS Code** above, or add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "flytoday": { "type": "stdio", "command": "uvx", "args": ["flytoday-mcp"] }
  }
}
```
</details>

<details>
<summary><b>Anything else</b></summary>

It's a standard stdio MCP server: run `uvx flytoday-mcp`, or `pip install flytoday-mcp` and run `flytoday-mcp`.
</details>

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."
- <span dir="rtl">ارزان&zwnj;ترین اتوبوس VIP تهران به اصفهان دوشنبه بعد؟</span>

## How it works

```text
  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`).

<details open>
<summary><b>✈️ Flights</b> (4)</summary>

| 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 |
</details>

<details open>
<summary><b>🏨 Hotels and stays</b> (6)</summary>

| 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 |
</details>

<details open>
<summary><b>🚆 Trains</b> (4)</summary>

| 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 |
</details>

<details open>
<summary><b>🚌 Buses</b> (3)</summary>

| 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