mrbilit-mcp 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (78) hide show
  1. mrbilit_mcp-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml +42 -0
  2. mrbilit_mcp-0.1.0/.github/ISSUE_TEMPLATE/config.yml +5 -0
  3. mrbilit_mcp-0.1.0/.github/banner.png +0 -0
  4. mrbilit_mcp-0.1.0/.github/dependabot.yml +10 -0
  5. mrbilit_mcp-0.1.0/.github/workflows/ci.yml +22 -0
  6. mrbilit_mcp-0.1.0/.github/workflows/publish.yml +51 -0
  7. mrbilit_mcp-0.1.0/.gitignore +6 -0
  8. mrbilit_mcp-0.1.0/LICENSE +21 -0
  9. mrbilit_mcp-0.1.0/PKG-INFO +365 -0
  10. mrbilit_mcp-0.1.0/README.md +339 -0
  11. mrbilit_mcp-0.1.0/pyproject.toml +54 -0
  12. mrbilit_mcp-0.1.0/server.json +32 -0
  13. mrbilit_mcp-0.1.0/src/mrbilit_mcp/__init__.py +5 -0
  14. mrbilit_mcp-0.1.0/src/mrbilit_mcp/buses.py +293 -0
  15. mrbilit_mcp-0.1.0/src/mrbilit_mcp/content.py +230 -0
  16. mrbilit_mcp-0.1.0/src/mrbilit_mcp/flights.py +381 -0
  17. mrbilit_mcp-0.1.0/src/mrbilit_mcp/hotels.py +364 -0
  18. mrbilit_mcp-0.1.0/src/mrbilit_mcp/http.py +199 -0
  19. mrbilit_mcp-0.1.0/src/mrbilit_mcp/places.py +231 -0
  20. mrbilit_mcp-0.1.0/src/mrbilit_mcp/registry.py +16 -0
  21. mrbilit_mcp-0.1.0/src/mrbilit_mcp/server.py +64 -0
  22. mrbilit_mcp-0.1.0/src/mrbilit_mcp/snapshot.json +1 -0
  23. mrbilit_mcp-0.1.0/src/mrbilit_mcp/trains.py +391 -0
  24. mrbilit_mcp-0.1.0/tests/conftest.py +98 -0
  25. mrbilit_mcp-0.1.0/tests/fixtures/airlines.json +51 -0
  26. mrbilit_mcp-0.1.0/tests/fixtures/airport_search.json +28 -0
  27. mrbilit_mcp-0.1.0/tests/fixtures/bus_cities.json +354 -0
  28. mrbilit_mcp-0.1.0/tests/fixtures/bus_companies.json +68 -0
  29. mrbilit_mcp-0.1.0/tests/fixtures/bus_min_prices.json +33 -0
  30. mrbilit_mcp-0.1.0/tests/fixtures/bus_nearby.json +43 -0
  31. mrbilit_mcp-0.1.0/tests/fixtures/bus_search.json +432 -0
  32. mrbilit_mcp-0.1.0/tests/fixtures/bus_seats.json +224 -0
  33. mrbilit_mcp-0.1.0/tests/fixtures/chunk_airports.js +2 -0
  34. mrbilit_mcp-0.1.0/tests/fixtures/chunk_stations.js +2 -0
  35. mrbilit_mcp-0.1.0/tests/fixtures/faqs.json +49 -0
  36. mrbilit_mcp-0.1.0/tests/fixtures/flight_baggage.json +6 -0
  37. mrbilit_mcp-0.1.0/tests/fixtures/flight_fare_rules.txt +1 -0
  38. mrbilit_mcp-0.1.0/tests/fixtures/flight_min_prices.json +72 -0
  39. mrbilit_mcp-0.1.0/tests/fixtures/flight_search.json +696 -0
  40. mrbilit_mcp-0.1.0/tests/fixtures/flight_search_back.json +506 -0
  41. mrbilit_mcp-0.1.0/tests/fixtures/flight_search_intl_rt.json +608 -0
  42. mrbilit_mcp-0.1.0/tests/fixtures/hotel_autocomplete.json +63 -0
  43. mrbilit_mcp-0.1.0/tests/fixtures/hotel_calendar.json +42 -0
  44. mrbilit_mcp-0.1.0/tests/fixtures/hotel_detail.json +300 -0
  45. mrbilit_mcp-0.1.0/tests/fixtures/hotel_rooms.json +235 -0
  46. mrbilit_mcp-0.1.0/tests/fixtures/hotel_search.json +464 -0
  47. mrbilit_mcp-0.1.0/tests/fixtures/hotel_static.json +270 -0
  48. mrbilit_mcp-0.1.0/tests/fixtures/mag_posts.json +26 -0
  49. mrbilit_mcp-0.1.0/tests/fixtures/masir.json +282 -0
  50. mrbilit_mcp-0.1.0/tests/fixtures/messages.json +30 -0
  51. mrbilit_mcp-0.1.0/tests/fixtures/nearby_airports.json +23 -0
  52. mrbilit_mcp-0.1.0/tests/fixtures/route_content.json +50 -0
  53. mrbilit_mcp-0.1.0/tests/fixtures/site_entry.js +2 -0
  54. mrbilit_mcp-0.1.0/tests/fixtures/site_home.html +1 -0
  55. mrbilit_mcp-0.1.0/tests/fixtures/support_help.json +44 -0
  56. mrbilit_mcp-0.1.0/tests/fixtures/taxi_cities.json +104 -0
  57. mrbilit_mcp-0.1.0/tests/fixtures/taxi_search.json +378 -0
  58. mrbilit_mcp-0.1.0/tests/fixtures/terms.json +21 -0
  59. mrbilit_mcp-0.1.0/tests/fixtures/train_companies.json +78 -0
  60. mrbilit_mcp-0.1.0/tests/fixtures/train_min_prices.json +20 -0
  61. mrbilit_mcp-0.1.0/tests/fixtures/train_nearby.json +36 -0
  62. mrbilit_mcp-0.1.0/tests/fixtures/train_pricing.json +31 -0
  63. mrbilit_mcp-0.1.0/tests/fixtures/train_search.json +615 -0
  64. mrbilit_mcp-0.1.0/tests/fixtures/train_stops.json +26 -0
  65. mrbilit_mcp-0.1.0/tests/test_buses.py +156 -0
  66. mrbilit_mcp-0.1.0/tests/test_content.py +99 -0
  67. mrbilit_mcp-0.1.0/tests/test_flights.py +235 -0
  68. mrbilit_mcp-0.1.0/tests/test_hotels.py +179 -0
  69. mrbilit_mcp-0.1.0/tests/test_http.py +63 -0
  70. mrbilit_mcp-0.1.0/tests/test_live_buses.py +33 -0
  71. mrbilit_mcp-0.1.0/tests/test_live_content.py +26 -0
  72. mrbilit_mcp-0.1.0/tests/test_live_flights.py +29 -0
  73. mrbilit_mcp-0.1.0/tests/test_live_hotels.py +35 -0
  74. mrbilit_mcp-0.1.0/tests/test_live_places.py +18 -0
  75. mrbilit_mcp-0.1.0/tests/test_live_trains.py +41 -0
  76. mrbilit_mcp-0.1.0/tests/test_places.py +121 -0
  77. mrbilit_mcp-0.1.0/tests/test_trains.py +187 -0
  78. mrbilit_mcp-0.1.0/uv.lock +1112 -0
@@ -0,0 +1,42 @@
1
+ name: Bug report
2
+ description: A tool failed or returned wrong data
3
+ labels: [bug]
4
+ body:
5
+ - type: input
6
+ id: tool
7
+ attributes:
8
+ label: Tool
9
+ description: Which tool, e.g. mb_search_flights
10
+ validations:
11
+ required: true
12
+ - type: textarea
13
+ id: input
14
+ attributes:
15
+ label: Arguments and result
16
+ description: The arguments the agent sent and the error or wrong output. Remove anything personal.
17
+ render: json
18
+ validations:
19
+ required: true
20
+ - type: textarea
21
+ id: expected
22
+ attributes:
23
+ label: What you expected
24
+ description: e.g. the price shown on mrbilit.com for the same route, date and passengers
25
+ - type: input
26
+ id: client
27
+ attributes:
28
+ label: MCP client and OS
29
+ placeholder: Claude Desktop 1.x on Windows 11
30
+ - type: dropdown
31
+ id: network
32
+ attributes:
33
+ label: Network
34
+ options:
35
+ - Iranian IP, no VPN
36
+ - VPN or proxy
37
+ - MRBILIT_MCP_PROXY set
38
+ - type: input
39
+ id: version
40
+ attributes:
41
+ label: mrbilit-mcp version
42
+ placeholder: "0.1.0"
@@ -0,0 +1,5 @@
1
+ blank_issues_enabled: true
2
+ contact_links:
3
+ - name: Question or idea
4
+ url: https://github.com/sepehr071/mrbilit-mcp/discussions
5
+ about: Ask how to use it or suggest a new tool
Binary file
@@ -0,0 +1,10 @@
1
+ version: 2
2
+ updates:
3
+ - package-ecosystem: github-actions
4
+ directory: /
5
+ schedule:
6
+ interval: monthly
7
+ - package-ecosystem: uv
8
+ directory: /
9
+ schedule:
10
+ interval: monthly
@@ -0,0 +1,22 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+
8
+ jobs:
9
+ test:
10
+ runs-on: ubuntu-latest
11
+ strategy:
12
+ matrix:
13
+ python: ["3.10", "3.11", "3.12", "3.13"]
14
+ steps:
15
+ - uses: actions/checkout@v7
16
+ - uses: astral-sh/setup-uv@v10.2.0
17
+ with:
18
+ python-version: ${{ matrix.python }}
19
+ - run: uv sync --locked
20
+ - run: uv run ruff check .
21
+ - run: uv run ruff format --check .
22
+ - run: uv run pytest -q
@@ -0,0 +1,51 @@
1
+ name: Publish
2
+
3
+ # Tag a release (git tag v0.1.0 && git push --tags) after bumping the version in
4
+ # pyproject.toml and server.json.
5
+ on:
6
+ push:
7
+ tags: ["v*"]
8
+
9
+ jobs:
10
+ pypi:
11
+ runs-on: ubuntu-latest
12
+ environment: pypi
13
+ permissions:
14
+ id-token: write # PyPI trusted publishing
15
+ contents: write # GitHub Release
16
+ steps:
17
+ - uses: actions/checkout@v7
18
+ - uses: astral-sh/setup-uv@v10.2.0
19
+ - name: Check versions match the tag
20
+ run: |
21
+ TAG=${GITHUB_REF_NAME#v}
22
+ grep -q "^version = \"$TAG\"" pyproject.toml
23
+ test "$(jq -r .version server.json)" = "$TAG"
24
+ test "$(jq -r '.packages[0].version' server.json)" = "$TAG"
25
+ - run: uv sync --locked && uv run pytest -q
26
+ - run: uv build
27
+ - uses: pypa/gh-action-pypi-publish@release/v1
28
+ - run: gh release create "$GITHUB_REF_NAME" dist/* --generate-notes --title "$GITHUB_REF_NAME"
29
+ env:
30
+ GH_TOKEN: ${{ github.token }}
31
+
32
+ mcp-registry:
33
+ needs: pypi
34
+ runs-on: ubuntu-latest
35
+ permissions:
36
+ id-token: write # MCP Registry login via GitHub OIDC
37
+ contents: read
38
+ steps:
39
+ - uses: actions/checkout@v7
40
+ - name: Wait for PyPI to serve the new version
41
+ run: |
42
+ for i in $(seq 1 30); do
43
+ curl -sf "https://pypi.org/pypi/mrbilit-mcp/${GITHUB_REF_NAME#v}/json" >/dev/null && exit 0
44
+ sleep 10
45
+ done
46
+ exit 1
47
+ - name: Install mcp-publisher
48
+ run: |
49
+ curl -L "https://github.com/modelcontextprotocol/registry/releases/download/v1.8.1/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
50
+ - run: ./mcp-publisher login github-oidc
51
+ - run: ./mcp-publisher publish
@@ -0,0 +1,6 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.pyc
4
+ dist/
5
+ .pytest_cache/
6
+ .ruff_cache/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Sepehr
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,365 @@
1
+ Metadata-Version: 2.5
2
+ Name: mrbilit-mcp
3
+ Version: 0.1.0
4
+ Summary: Unofficial read-only MCP server for MrBilit: cheapest flights, trains, buses, taxis and hotels in Iran, with seats, refund rules and exact prices.
5
+ Project-URL: Homepage, https://github.com/sepehr071/mrbilit-mcp
6
+ Project-URL: Source, https://github.com/sepehr071/mrbilit-mcp
7
+ Project-URL: Changelog, https://github.com/sepehr071/mrbilit-mcp/releases
8
+ Project-URL: Issues, https://github.com/sepehr071/mrbilit-mcp/issues
9
+ Author-email: Sepehr <sepehr@nextofx.com>
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: bus,flights,hotel,iran,mcp,model-context-protocol,mrbilit,train,travel
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
22
+ Requires-Python: >=3.10
23
+ Requires-Dist: httpx>=0.27
24
+ Requires-Dist: mcp<3,>=2.2
25
+ Description-Content-Type: text/markdown
26
+
27
+ <!-- mcp-name: io.github.sepehr071/mrbilit-mcp -->
28
+
29
+ <div align="center">
30
+
31
+ <img src="https://raw.githubusercontent.com/sepehr071/mrbilit-mcp/main/.github/banner.png" alt="mrbilit-mcp: let your AI agent find the cheapest way to travel in Iran" width="100%">
32
+
33
+ # ✈️ mrbilit-mcp
34
+
35
+ **Let your AI agent plan trips in Iran with MrBilit.**<br>
36
+ Find the cheapest flight, train, bus or private taxi on a date or over a month, see seats, baggage and refund rules,<br>
37
+ and compare hotels with exact room prices, all from Claude, Cursor or Copilot.
38
+
39
+ [![PyPI](https://img.shields.io/pypi/v/mrbilit-mcp?color=2563eb)](https://pypi.org/project/mrbilit-mcp/)
40
+ [![Python](https://img.shields.io/pypi/pyversions/mrbilit-mcp)](https://pypi.org/project/mrbilit-mcp/)
41
+ [![CI](https://github.com/sepehr071/mrbilit-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sepehr071/mrbilit-mcp/actions/workflows/ci.yml)
42
+ [![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.sepehr071%2Fmrbilit--mcp-7c3aed)](https://registry.modelcontextprotocol.io/?q=mrbilit-mcp)
43
+ [![License: MIT](https://img.shields.io/badge/license-MIT-16a34a)](https://github.com/sepehr071/mrbilit-mcp/blob/main/LICENSE)
44
+
45
+ [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=mrbilit&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJtcmJpbGl0LW1jcCJdfQ==)
46
+ [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_mrbilit--mcp-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=mrbilit&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mrbilit-mcp%22%5D%7D)
47
+
48
+ [Quick start](#quick-start) · [What it can do](#what-it-can-do) · [Tools](#tools) · [FAQ](#faq) · [فارسی](#فارسی)
49
+
50
+ </div>
51
+
52
+ ---
53
+
54
+ ## Why
55
+
56
+ MrBilit (mrbilit.com, مستربلیط) sells flights, trains, intercity buses, private taxis and hotels in one place, but
57
+ each one has its own search, calendar and rules. Comparing "plane or train or bus, which day, which seat" means
58
+ a dozen page loads. An agent with `mrbilit-mcp` does it in one go:
59
+
60
+ > **You:** Cheapest way to get from Tehran to Mashhad on 20 October?
61
+ >
62
+ > **Agent:** *calls* `mb_search_flights(origin="THR", destination="MHD", date="2026-10-20")`,
63
+ > `mb_train_price_calendar(origin=1, destination=191)`, `mb_search_buses(origin=11320000, destination=31310000, date="2026-10-20", sort="cheapest")`
64
+ >
65
+ > | Mode | Cheapest option | Departs | Price (Toman) |
66
+ > |---|---|---|---|
67
+ > | Bus | Peyk Saba VIP, Tehran South terminal, 17 seats left | 21:00, arrives 09:00 | **1,313,000** |
68
+ > | Train | cheapest seat that day | | 760,000 |
69
+ > | Flight | Mehr Air MEH 4200, Mehrabad, 2 seats left | 08:30, arrives 09:30 | 11,856,000 |
70
+ >
71
+ > The train is cheapest; want me to list that day's trains and free seats with `mb_search_trains`?
72
+
73
+ <sub>Real tool output from 2026-10-04; prices and seats change all the time. Prices are in Toman.</sub>
74
+
75
+ ## What it can do
76
+
77
+ - ✈️ **Flights**: domestic and international, one-way or round trip, party prices, cabin/airline/direct/time filters
78
+ - 📅 **Cheapest day** for flights, trains and buses over weeks, and the cheapest nights of a hotel
79
+ - 🚆 **Trains**: every class with free seats, exact price for children, infants or a whole compartment, every stop
80
+ - 🚌 **Buses and taxis**: terminals, companies, VIP, seat maps with women/men seats, private door-to-door cars
81
+ - 🔀 **Alternatives** when trains are full: one-change trips, nearby stations, bus routes and airports
82
+ - 🏨 **Hotels**: available stays with prices, every hotel of a city, guest ratings and reviews, rooms and exact prices
83
+ - 📢 **Context**: current site notices, official refund and baggage rules, help-center guides, route guides
84
+ - 🔒 **Read-only by design**: no login, no seat hold, no booking, no payment
85
+
86
+ ## Quick start
87
+
88
+ You need [uv](https://docs.astral.sh/uv/getting-started/installation/).
89
+
90
+ <details open>
91
+ <summary><b>Claude Code</b></summary>
92
+
93
+ ```bash
94
+ claude mcp add mrbilit -- uvx mrbilit-mcp
95
+ ```
96
+
97
+ Outside Iran, if MrBilit's API does not answer, add a proxy:
98
+
99
+ ```bash
100
+ claude mcp add mrbilit -e MRBILIT_MCP_PROXY=http://127.0.0.1:8080 -- uvx mrbilit-mcp
101
+ ```
102
+ </details>
103
+
104
+ <details>
105
+ <summary><b>Claude Desktop</b></summary>
106
+
107
+ Settings → Developer → Edit Config, then add:
108
+
109
+ ```json
110
+ {
111
+ "mcpServers": {
112
+ "mrbilit": { "command": "uvx", "args": ["mrbilit-mcp"] }
113
+ }
114
+ }
115
+ ```
116
+
117
+ Need a proxy? Add `"env": { "MRBILIT_MCP_PROXY": "http://127.0.0.1:8080" }` next to `args`.
118
+ </details>
119
+
120
+ <details>
121
+ <summary><b>Cursor</b></summary>
122
+
123
+ Click **Install in Cursor** above, or add the Claude Desktop block to `~/.cursor/mcp.json`.
124
+ </details>
125
+
126
+ <details>
127
+ <summary><b>VS Code (Copilot agent mode)</b></summary>
128
+
129
+ Click **Install in VS Code** above, or add to `.vscode/mcp.json`:
130
+
131
+ ```json
132
+ {
133
+ "servers": {
134
+ "mrbilit": { "type": "stdio", "command": "uvx", "args": ["mrbilit-mcp"] }
135
+ }
136
+ }
137
+ ```
138
+ </details>
139
+
140
+ <details>
141
+ <summary><b>Anything else</b></summary>
142
+
143
+ It's a standard stdio MCP server: run `uvx mrbilit-mcp`, or `pip install mrbilit-mcp` and run `mrbilit-mcp`.
144
+ </details>
145
+
146
+ Then just ask:
147
+
148
+ - "Cheapest day to fly Tehran to Kish in the next month, and the baggage on that flight?"
149
+ - "Train from Tehran to Mashhad next Friday for 2 adults and a child: which classes have seats and what's the total?"
150
+ - "4-star hotels in Shiraz for 3 nights from the 20th under 3 million Toman a night, with their reviews."
151
+ - <span dir="rtl">ارزان&zwnj;ترین اتوبوس VIP تهران به اصفهان فردا شب و صندلی&zwnj;های خالی آن؟</span>
152
+
153
+ ## How it works
154
+
155
+ ```text
156
+ AI agent (Claude, Cursor, Copilot, ...)
157
+ │
158
+ │ MCP over stdio
159
+ ▼
160
+ mrbilit-mcp (runs on your machine)
161
+ │
162
+ │ HTTPS (REST, optional proxy)
163
+ ├──────▶ flight.atighgasht.com, train.mrbilit.com, masir.mrbilit.com, bus.mrbilit.ir, hotel.mrbilit.ir
164
+ └──────▶ content.mrbilit.ir, directus.mrbilit.ir, mrbilit.com (site lists, magazine)
165
+ ```
166
+
167
+ `mrbilit-mcp` runs locally and calls the same public endpoints the mrbilit.com website uses. There's no hosted
168
+ server in between, no API key, and nothing about you is sent anywhere else.
169
+
170
+ ## Tools
171
+
172
+ Every search takes the codes from `mb_find_place`: IATA codes for flights (`THR`, `MHD`, `ISTALL`), station ids for
173
+ trains (Tehran `1`, Mashhad `191`), 8-digit city ids for buses and taxis (Tehran `11320000`), slugs for hotels
174
+ (`mashhad`, `mashhad/enghelab`).
175
+
176
+ <details open>
177
+ <summary><b>📍 Places and companies</b> (2)</summary>
178
+
179
+ | Tool | What it does |
180
+ |---|---|
181
+ | `mb_find_place` | City, airport, station or hotel name → the code each search takes (flight, train, bus, taxi, hotel) |
182
+ | `mb_companies` | Airlines, rail operators, bus companies and taxi classes with their codes |
183
+ </details>
184
+
185
+ <details open>
186
+ <summary><b>✈️ Flights</b> (3)</summary>
187
+
188
+ | Tool | What it does |
189
+ |---|---|
190
+ | `mb_search_flights` | Flights on a date, one-way or round trip, domestic or international: price per adult and party total, seats, baggage; cabin, airline, direct and time filters |
191
+ | `mb_flight_price_calendar` | Cheapest fare per day over up to 180 days |
192
+ | `mb_flight_fare_details` | One flight or round-trip package's fares: refund penalties, checked baggage, fare rules, notes, adult/child/infant prices |
193
+ </details>
194
+
195
+ <details open>
196
+ <summary><b>🚆 Trains</b> (5)</summary>
197
+
198
+ | Tool | What it does |
199
+ |---|---|
200
+ | `mb_search_trains` | Trains on a date with every class, price per adult and fresh free-seat counts; men/women/general/car quotas |
201
+ | `mb_train_price_calendar` | Cheapest bookable train per day |
202
+ | `mb_train_price` | Exact price of a class for adults, children, infants, foreigners and empty berths, with the total |
203
+ | `mb_train_stops` | Every stop of a train with date and time |
204
+ | `mb_alternative_routes` | Trips with one change (any mix of train and bus) and nearby train, bus and flight routes |
205
+ </details>
206
+
207
+ <details open>
208
+ <summary><b>🚌 Buses and taxis</b> (4)</summary>
209
+
210
+ | Tool | What it does |
211
+ |---|---|
212
+ | `mb_search_buses` | Buses on a date: company, terminal, times, price per seat, free seats, VIP, stops, refund penalties |
213
+ | `mb_bus_price_calendar` | Cheapest bus seat per day |
214
+ | `mb_bus_seats` | Seat map: free seats, seats sold to women and men, row layout with the aisle |
215
+ | `mb_search_taxis` | Private door-to-door intercity taxis, price per car, by class and pick-up slot |
216
+ </details>
217
+
218
+ <details open>
219
+ <summary><b>🏨 Hotels</b> (5)</summary>
220
+
221
+ | Tool | What it does |
222
+ |---|---|
223
+ | `mb_search_hotels` | Available hotels in a city for dates with the cheapest stay price; stars, type, price and refund filters |
224
+ | `mb_hotel` | One hotel: rating, latest reviews with per-criterion scores, location, landmarks, rules, amenities |
225
+ | `mb_hotel_rooms` | Every room with its exact price for the dates, per night, rooms left, meals |
226
+ | `mb_hotel_calendar` | Cheapest one-night price per night, up to ~48 nights ahead |
227
+ | `mb_city_hotels` | Every hotel of a city, sold out ones included, filtered by stars, type or name (no prices) |
228
+ </details>
229
+
230
+ <details open>
231
+ <summary><b>📢 Notices and help</b> (3)</summary>
232
+
233
+ | Tool | What it does |
234
+ |---|---|
235
+ | `mb_notices` | Notices MrBilit shows right now for a service or route |
236
+ | `mb_help` | Search the official rules, FAQ and help-center guides (refunds, baggage, auto-reserve, ...) |
237
+ | `mb_travel_guide` | Route or city guide (summary, FAQ, article) and travel-magazine posts |
238
+ </details>
239
+
240
+ All 22 tools are annotated `readOnlyHint: true` and return compact structured JSON, so they don't flood the agent's context.
241
+
242
+ ## Good to know
243
+
244
+ - **Prices are in Toman** in every tool (the API sends Rial; values are divided by 10), always in fields named `*_toman`.
245
+ Flight `price_toman` is per adult and `total_toman` the whole party; trains per adult; buses per seat; taxis per car;
246
+ hotels the whole stay for one room.
247
+ - **Dates** in and out are Gregorian `YYYY-MM-DD`; past dates are rejected. Times are local to the place: a flight
248
+ time at a foreign airport is that airport's local time, although the API puts `+03:30` on every flight time.
249
+ - **Ratings are 0–5**; `null` means not rated. The site shows hotel ratings ×2 out of 10.
250
+ - **Ids expire**: `flight_id`, `class_id` and `bus_id` come from a fresh search.
251
+ - **Sales windows**: trains open about 18 days ahead, buses about a month. An empty result often just means "not on sale yet".
252
+ - **Round trips**: domestic flights are two separate tickets (two lists); international round trips are priced as one package.
253
+ - **Hotel prices do not depend on the guest count**: pick rooms whose `sleeps` fits, and add rooms up for a group.
254
+ - Domestic airports and train stations come from the site's own bundled lists, fetched once per run with a copy
255
+ shipped in the package as a fallback.
256
+
257
+ ## FAQ
258
+
259
+ <details>
260
+ <summary><b>Do I need a proxy?</b></summary>
261
+
262
+ Usually not: direct calls from an Iranian connection work. If your network cannot reach MrBilit's API servers
263
+ (connections time out or are reset), set `MRBILIT_MCP_PROXY` to an HTTP proxy that can reach them.
264
+ System proxy variables (`HTTPS_PROXY`, ...) are ignored on purpose.
265
+ </details>
266
+
267
+ <details>
268
+ <summary><b>Can it book a ticket for me?</b></summary>
269
+
270
+ No, and that's deliberate. It has no login and never holds a seat, reserves, orders or pays. The agent finds the
271
+ best option; you book on mrbilit.com.
272
+ </details>
273
+
274
+ <details>
275
+ <summary><b>I get "did not answer in time" or "Could not reach"</b></summary>
276
+
277
+ The server retries a reset connection once. If it keeps failing, set `MRBILIT_MCP_PROXY` (see above). The one-change
278
+ trip search (`mb_alternative_routes`) is known to hang now and then; it is retried and its other parts are still returned.
279
+ </details>
280
+
281
+ <details>
282
+ <summary><b>Why does a sold-out train class still have a price in <code>mb_train_price</code>?</b></summary>
283
+
284
+ The pricing endpoint prices any class; availability comes from `mb_search_trains` (`seats_left`, `bookable`).
285
+ </details>
286
+
287
+ <details>
288
+ <summary><b>Claude Desktop says <code>uvx</code> is not found</b></summary>
289
+
290
+ Use the full path to `uvx` (`where uvx` on Windows, `which uvx` on macOS/Linux) as `command`.
291
+ </details>
292
+
293
+ <details>
294
+ <summary><b>How do I debug what the agent sees?</b></summary>
295
+
296
+ ```bash
297
+ npx @modelcontextprotocol/inspector uvx mrbilit-mcp
298
+ ```
299
+ </details>
300
+
301
+ ## Configuration
302
+
303
+ | Variable | Default | Meaning |
304
+ |---|---|---|
305
+ | `MRBILIT_MCP_PROXY` | unset | HTTP proxy for every request, e.g. `http://user:pass@host:port`. Usually not needed in Iran |
306
+
307
+ ## Safety
308
+
309
+ - Read-only: no login or OTP, no seat hold, reservation, order, payment, wallet, price alert or review posting.
310
+ The only POSTs are searches and price lookups the site itself makes before booking.
311
+ - Admin fields (`created_by`, `updated_by`) of the content CMS are never passed through.
312
+ - Always sends a browser User-Agent and at most two requests at a time, since the API hosts share one server.
313
+
314
+ ## فارسی
315
+
316
+ <div dir="rtl">
317
+
318
+ **mrbilit-mcp** به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه می&zwnj;دهد در مستربلیط ارزان&zwnj;ترین
319
+ پرواز، قطار، اتوبوس یا تاکسی دربستی را برای یک روز یا یک ماه پیدا کند، صندلی&zwnj;های خالی، بار مجاز و قوانین استرداد را ببیند
320
+ و هتل&zwnj;ها را با قیمت دقیق اتاق و نظرات مسافران مقایسه کند.
321
+
322
+ - فقط خواندنی است: وارد حساب نمی&zwnj;شود و صندلی رزرو یا بلیط صادر نمی&zwnj;کند.
323
+ - همه قیمت&zwnj;ها به تومان است.
324
+ - روی سیستم خود شما اجرا می&zwnj;شود و به هیچ سرور واسطی داده نمی&zwnj;فرستد.
325
+ - در ایران معمولاً نیازی به پروکسی نیست؛ اگر سرورهای مستربلیط پاسخ ندادند، `MRBILIT_MCP_PROXY` را تنظیم کنید.
326
+
327
+ **نصب در Claude Code:**
328
+
329
+ </div>
330
+
331
+ ```bash
332
+ claude mcp add mrbilit -- uvx mrbilit-mcp
333
+ ```
334
+
335
+ <div dir="rtl">
336
+
337
+ بعد بپرسید: «ارزان&zwnj;ترین راه رفتن از تهران به مشهد در ۲۸ مهر چیست؟»
338
+
339
+ </div>
340
+
341
+ ## Development
342
+
343
+ ```bash
344
+ git clone https://github.com/sepehr071/mrbilit-mcp && cd mrbilit-mcp
345
+ uv sync
346
+ uv run pytest # offline, against recorded responses
347
+ uv run pytest -m live # real API (set MRBILIT_MCP_PROXY if needed)
348
+ uv run ruff check .
349
+ ```
350
+
351
+ Tools live in `src/mrbilit_mcp/places.py`, `flights.py`, `trains.py`, `buses.py`, `hotels.py` and `content.py`; each
352
+ is a typed async function with a docstring that tells the agent when to use it. Issues and PRs are welcome,
353
+ especially new tools and fixes for API changes.
354
+
355
+ Releases: bump the version in `pyproject.toml` and `server.json`, then push a `v*` tag. GitHub Actions tests,
356
+ publishes to PyPI and the [MCP Registry](https://registry.modelcontextprotocol.io), and creates the GitHub Release.
357
+
358
+ ## Disclaimer
359
+
360
+ Unofficial and not affiliated with or endorsed by MrBilit. It uses the public endpoints of the mrbilit.com website,
361
+ which can change without notice. Please keep request rates reasonable.
362
+
363
+ ## License
364
+
365
+ [MIT](https://github.com/sepehr071/mrbilit-mcp/blob/main/LICENSE)