Skip to content
Back to search

ouigo-iryo

Ouigo España fares in your terminal and AI agent (CLI + MCP), plus ready-made Iryo booking links. Same JSON as renfe-cli. Unofficial; no login, no credentials.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zheng2026--ouigo-iryo/badge.svg)](/listings/zheng2026--ouigo-iryo)

HTML

<a href="/listings/zheng2026--ouigo-iryo"><img src="/api/listings/zheng2026--ouigo-iryo/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

You need Python 3.12+, [uv](https://docs.astral.sh/uv/) and **Google Chrome** installed. The tool drives your own Chrome, so there's no separate browser download.

uv tool install git+https://github.com/zheng2026/ouigo-iryo
ouigo --help

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 154 lines
  1. # ouigo-iryo
  2. **Ouigo España fares in your terminal and in your AI agent.** Trains, all three fare levels and the cheapest day of the month, as JSON. Plus a ready-made Iryo booking link. Unofficial, not affiliated with Ouigo or Iryo.
  3. <p align="center">
  4. <img src="docs/demo.svg" alt="ouigo CLI demo: the cheapest December day from Madrid to Valencia, the three cheapest trains on one day, and Ouigo's own booking page opened with the date filled in" width="860">
  5. </p>
  6. <p align="center">
  7. <a href="LICENSE"><img alt="MIT licence" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
  8. <img alt="Python 3.12+" src="https://img.shields.io/badge/python-3.12%2B-blue.svg">
  9. <img alt="Output: JSON" src="https://img.shields.io/badge/output-JSON-informational.svg">
  10. <img alt="MCP server included" src="https://img.shields.io/badge/MCP-server-8A2BE2.svg">
  11. </p>
  12. Renfe already has a great open CLI ([luisgonzaleznf/renfe-cli](https://github.com/luisgonzaleznf/renfe-cli)). Ouigo had nothing that works without borrowing the website's own login. This fills that gap, and speaks the **same JSON** as renfe-cli, so you can compare Renfe, Avlo and Ouigo trains in one list.
  13. ## What it does
  14. - **`search`**: every Ouigo train on a day, with times, the real departure station (Atocha or Chamartín) and all fares (Esencial, Plus, Full), cheapest first.
  15. - **`calendar`**: the cheapest price for each day in a date range. Find the €9 day before you pick the train.
  16. - **`open`**: Ouigo's own booking page with route **and date** filled in. You choose and pay there; this tool never touches payment.
  17. - **`stations`**: Ouigo's stations, matched by name (accents and case ignored) with typo suggestions.
  18. - **`iryo`**: a ready-made link to Iryo's own booking page for your route and date. No fares (see below).
  19. - **MCP server**: the same four abilities for Claude Desktop, Claude Code or any MCP client.
  20. ## Install
  21. You need Python 3.12+, [uv](https://docs.astral.sh/uv/) and **Google Chrome** installed. The tool drives your own Chrome, so there's no separate browser download.
  22. ```sh
  23. uv tool install git+https://github.com/zheng2026/ouigo-iryo
  24. ouigo --help
  25. ```
  26. ## Quick start
  27. ```sh
  28. ouigo stations valencia
  29. ouigo calendar Madrid Valencia --from 2026-12-01 --to 2026-12-31 # cheapest price per day
  30. ouigo search Madrid Valencia -d 2026-12-15 # trains in departure order
  31. ouigo search Madrid Valencia -d 2026-12-15 --sort price --limit 3 # cheapest first
  32. ouigo search Madrid Barcelona -d 2026-12-12 --after 17:00
  33. ouigo open Madrid Valencia -d 2026-12-15 # Ouigo's page, ready to book
  34. ```
  35. Pipe it anywhere:
  36. ```sh
  37. ouigo search Madrid Valencia -d 2026-12-15 --sort price --limit 3 \
  38. | jq -r '.trains[] | "\(.departure[11:16]) \(.service) from \(.fares[0].price) €"'
  39. # 07:15 06472 from 9 €
  40. # 12:15 06822 from 17 €
  41. # 17:45 06572 from 19 €
  42. ```
  43. ### Ouigo and Renfe in one list
  44. Both tools print the same layout, so merging them is one `jq` line (with [renfe-cli](https://github.com/luisgonzaleznf/renfe-cli) installed):
  45. ```sh
  46. { ouigo search Madrid Valencia -d 2026-12-15; renfe search Madrid Valencia -d 2026-12-15; } \
  47. | jq -s '[.[].trains[]] | sort_by(.fares[0].price) | .[:5][] | {type, service, departure, price: .fares[0].price}'
  48. ```
  49. ## Use it from an AI agent (MCP)
  50. <p align="center">
  51. <img src="docs/demo-claude.gif" alt="A real Claude Desktop chat, sped up (badges show the speed): asked for the cheapest Valencia–Madrid day trip in December 2026, it finds Wednesday 16 December at €32 return with Ouigo, gives Ouigo's booking links for both directions and Iryo's link for the same day, which are then opened" width="860">
  52. </p>
  53. Ask in plain words; the assistant picks the tools. This is a real run, lightly shortened ([full transcript](docs/mcp_transcript.md)):
  54. <p align="center">
  55. <img src="docs/mcp-demo.svg" alt="An AI assistant asked for the cheapest Ouigo day from Madrid to Valencia in December calls cheapest_days, then search_trains, and answers: 9 euros on 1, 2, 15 and 16 December, with the four trains on 1 December and a link to book on Ouigo's page" width="860">
  56. </p>
  57. ```json
  58. {
  59. "mcpServers": {
  60. "ouigo": { "command": "/Users/YOU/.local/bin/ouigo-mcp" }
  61. }
  62. }
  63. ```
  64. After `uv tool install`, the `ouigo-mcp` command lives in `~/.local/bin`. Desktop apps don't read your shell's PATH, so give the full path (`which ouigo-mcp` prints it).
  65. Tools: `search_trains(origin, destination, date)`, `cheapest_days(origin, destination, start, end)`, `find_station(query)`, `shop_link(origin, destination, date)`, `iryo_link(origin, destination, date)` (link only, no fares).
  66. Tip: in Claude, Sonnet answers these questions noticeably faster than Opus.
  67. Ouigo answers (`search_trains`, `cheapest_days`) also carry an `iryo` link for the same route and day, and the server tells the assistant to show it, so both companies appear in one answer.
  68. ## Iryo: a ready link, no fares
  69. ```sh
  70. iryo open Madrid Valencia -d 2026-12-15 # opens Iryo's page in your browser
  71. iryo open Madrid Valencia -d 2026-12-15 --print # just print the link (--json for details)
  72. iryo stations sevilla
  73. ```
  74. Iryo blocks automated access, so this tool never contacts Iryo: it only builds the link, and you open it and see the trains and fares there. "Madrid" means all Madrid stations. Iryo's València trains use Chamartín, not Atocha; if you pick a pair Iryo is known not to run, you get a warning (the page would say "No hay datos de billetes").
  75. Ouigo `search` and `calendar` results include both companies' links for the same day (the cheapest day for `calendar`): `shop` for Ouigo and `iryo` for Iryo (`null` if Iryo does not serve the pair).
  76. ## How it works, and what it never does
  77. Your installed Chrome opens Ouigo's **public search page** headlessly, exactly as if you'd opened it, and the tool reads the results that page receives.
  78. - **No login and no credentials.** It never reads, stores or replays tokens or headers, and never calls Ouigo's servers on its own.
  79. - **No bot-check evasion.** No stealth plugins, no fingerprint tricks, no proxies. If Ouigo shows a challenge or answers 403, it stops and says `blocked`.
  80. - **Gentle:** one page at a time, at least 2 seconds apart, and one retry on a plain timeout.
  81. - **Never pays.** `open` hands you Ouigo's page; buying is between you and Ouigo.
  82. ## Output and errors
  83. `search` uses renfe-cli's keys: `date`, `origin`, `destination`, `passengers`, `fares_included`, `notice`, `count`, `trains`, `shop`, `delays_included`, `retries`. Each train has `service`, `type` (`"OUIGO"`), `departure` and `arrival` as full local timestamps, `duration_minutes`, `changes`, `available`, and `fares` (`{name, price, currency}`, cheapest first). Ouigo publishes no live delays, so `delay_minutes` and `live_train` are always `null`. Extras: `source`, `fetched_at`, `origin_station`/`destination_station` per train, and a `family` per fare. A day with no trains isn't an error: `count` is 0 and `notice` says so.
  84. `calendar` returns `days` (`date`, `price`, `is_promo`, `is_best_price`) and `cheapest`.
  85. Errors go to stderr as `{"error": {"code": …}}`, with renfe-cli's exit codes:
  86. | Code | Meaning |
  87. |---|---|
  88. | `0` | ok; check `notice` |
  89. | `1` | internal error (only the exception type is shown), or Chrome not found |
  90. | `2` | usage: unknown station (with suggestions), bad date, bad input |
  91. | `5` | blocked or upstream: challenge page, 403/429, timeout |
  92. | `7` | Ouigo changed its site and the response no longer parses |
  93. ## Limits
  94. - Slow-ish: about 5–10 seconds per search, because a real browser loads the page.
  95. - It breaks when Ouigo redesigns its site. Exit code 7 tells you when.
  96. - Automated use may conflict with Ouigo's terms of use. Use it gently, for personal trip planning.
  97. - One adult, one way. Return trips and discount cards aren't supported yet.
  98. ## En español
  99. `ouigo-iryo` consulta los precios de Ouigo España desde la terminal o desde un agente de IA (MCP): trenes, las tres tarifas y el día más barato del mes, en JSON. Usa tu propio Chrome para abrir la página pública de búsqueda de Ouigo y leer lo que esa página recibe, sin iniciar sesión, sin credenciales y sin saltarse ninguna protección. Habla el mismo JSON que [renfe-cli](https://github.com/luisgonzaleznf/renfe-cli), así que puedes comparar Renfe, Avlo y Ouigo en una sola lista. No oficial; no afiliado a Ouigo ni a Iryo. Para Iryo solo construye el enlace a su página de reservas (`iryo open Madrid Valencia -d 2026-12-15`), sin precios: Iryo bloquea el acceso automático.
  100. ## Development
  101. ```sh
  102. uv sync
  103. uv run pytest # offline tests on recorded responses
  104. uv run pytest -m live # one real search
  105. python3 docs/make_demo.py # rebuilds docs/demo.svg (terminal)
  106. python3 docs/make_chat_demo.py # rebuilds docs/mcp-demo.svg (AI chat)
  107. ```
  108. ## Credit and licence
  109. The JSON layout and exit codes follow [luisgonzaleznf/renfe-cli](https://github.com/luisgonzaleznf/renfe-cli), which showed how good a JSON-first train CLI can be. MIT licence, © 2026 Jade Zheng.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.